How do I configure Entuity to automatically generate action requests?

What is forkevent?

To configure forkevent

Java Fork process

To configure automatic AR generation on all events

To determine which events result in automatic AR generation

You can configure Entuity to automatically generate action requests for AR System servers. This requires you to configure and run forkevent (see below). An AR can be triggered by the raising of an event that has an associated advanced action configured through the Entuity Integration for BMC Remedy AR System.

When Entuity raises an event, it checks against the forwarding filter to see if the event details should be forwarded to the AR System. Specifically, it checks if the raised event is:

• in the specified View, e.g. in the sample configuration, All Objects.
• of the specified type, e.g. in the sample configuration, all events are passed.

Event information is only passed to the specified form on the AR System when both conditions are met. The summary details are prefixed with Automated Event to identify the AR as automatically generated.

What is forkevent?

forkevent is configured through its own event action configuration file (remedyforkevent.cfg) in order for it to forward event information to the EventActionApplication. forkevent works in the following manner:

1. it uses details in the [connection] section to register with the event management process. forkevent becomes a client. The Entuity server only forwards to forkevent those events in the registered View.
2. it uses details in the [pipe_remedy] section when calling EventActionApplication. forkevent structures the event details, and sends the data to EventActionApplication using the stdin of the pipe process.

EventActionApplication uses the default configuration:

1. EventActionApplication uses the appropriate menu in sw_remedy_menu_def_menu.cfg to build a complete parameter list from forkevent's direct data, StormWorks' event object details, and Entuity host/user information.
2. EventActionApplication builds a string that contains the parameters and then passes it to the forked process arforward.

To configure forkevent:

Pipe process:

forkevent communicates with the database using Pipe. Each time forkevent recognizes an event, it sends the event data to the stdin of the Pipe process. The format and structure of the event data is taken from [data] section in the configuration file. In Pipe mode, forkevent sends event data in the following format:

VariableLabel VariableValue <CR>
BlankLine <CR>

Where:

• VariableLabel is the label assigned to the event data in the [data] section, e.g. Descr in Descr=${event.PAPIDescr}.
• VariableValue is the event data value, extracted from the [data] section, e.g. ${event.PAPIDescr} in Descr=${event.PAPIDescr}.
• <CR> is the end of line marker. Each value is passed on its own line.
• BlankLine is automatically sent at the end of the event data to signal the end of that event.

Remedy forkevent configuration:

The remedyforkevent.cfg file contains details required to access the Entuity database, and is used to determine the format of and order event data passed to the AR System.

The file contains three sections: Connection, Process and Data.

1. Connection sections - detail the information required to access Entuity to collect event data. The following is a sample connection section:

[connection]
username=admin
view=All Objects
extendedEvents=1

Where:

• [connection] is the name of the section that contains the details required to access Entuity event data.
• username is the Entuity login name.
• view is the Entuity View from which events are collected, by default All Objects. Only
  when an event occurs on a managed object within the defined View is it forwarded by forkevent. All Objects includes all managed objects, Entuity advise changing View to a more restricted View to only include events from required objects.
  
  username and View are the same details as used for accessing Entuity.
• extendedEvents sets the maximum number of characters that forkevent forwards for the event description. Event descriptions greater than this setting are truncated. When set to:
  
  • 0 (default), forwards event descriptions to a maximum of 127 characters
  • 1, forwards event descriptions to a maximum of 4095 characters.

2. Process sections - define the pipe process and its arguments. A configuration file can have more than one process definition, although only one definition is used at any one time. This definition is passed as an argument when forkevent is run. The following is a sample process section:

[pipe_remedy]
start=${install.JAVA} -Dlog4j.configuration=file:${ENTUITY_HOME}$
{FPS}etc${FPS}RemedyForkEventLoggerConf.xml
=-cp ${ENTUITY_HOME}${FPS}lib${FPS}httpd${FPS}EOS${FPS}EOSServer.jar
{EPS}${ENTUITY_HOME}${FPS}lib${FPS}httpd${FPS}EOS${FPS}log4j.jar
=com.entuity.eos.menu.EventActionApplication
=period=1000 appname=RemedyForkEvent userid=${activeuser}
webport=${webportnum}
args=
type=pipe
directory=${LOGDIR}

Where the following arguments may be passed to the menu application:

• [pipe_remedy] is the section name. This is passed as a parameter with the forkevent command.
• start runs the specified application with the set arguments:
  
  • maxactions, the maximum number of concurrently executing menu actions, by default 15. Once exceeded, Entuity queues remaining actions. It is optional, but when set must be 1 or greater.
  • timeout, the time after which an executing action can be removed from the pool and queued actions run. A timeout action can be terminated, or left for execution based on the value of terminate. 0 indicates no timeout, the default is 900000 ms, 15 minutes, and the minimum value is 100 ms.
  • terminate, when set to true, the default, terminates a timed-out action, false allows the action to complete.
  • period, specifies the minimum amount of time in milliseconds that must elapse between action executions, and is used to control throughput of action executions and system load. The default is 1000.
  • dshost, IP address or hostname of the Entuity StormWorks server, by default localhost.
  • dsport, Entuity StormWorks port, the default is 5467.
  • dstimeout, timeout for the Entuity StormWorks database connection. The default is 60 seconds.
  • appname, name of the application forkevent runs to gather the AR System data.
  • userid, the account name used to access Entuity.
  • clienthost, application's IP address, by default localhost.
  • eyeserver, IP address or hostname, and port of the Entuity web server, by default localhost:80. This attribute is used in place of webport but can also make use of it, for example where keli is the Entuity server hostname:
    eyeserver=keli:${webportnum}
  • webport, the port on which the Entuity web server is accessible, by default 80.
• args allow you to pass commandline arguments with the Pipe and Fork processes. They are not used with the Entuity Integration for BMC Remedy AR System integration.
• When type is pipe, start runs as soon as forkevent runs, creating the Pipe process.
• EmptyVariable is used to enter a value in an event variable passed from Entuity that does not contain any data, i.e. to make it easier to identify in the integrated package. By default, EMPTY_VARIABLE is entered. Using EmptyVariable you can replace that with one of your choice, e.g. MISSING_VALUE.
• directory is the directory from which the process is run and log files are written to.
• loglevel is the level of logging information recorded, i.e. errors, warning, info, debug and all.

3. Data sections - hold the associations between labels and Entuity event variables. These lables can be used by the Pipe process to identify and manipulate event data. There must only be one data section in an Event Forward configuration file.

The data section is only used with the Pipe process. The Pipe process runs continually, and it is only through the data section that arguments can be passed for each event. The Fork process is started for each event, and so arguments are passed each time an event occurs.

The following is an example of a data section:

[data]
event.PAPIId=${event.PAPIId}
event.PAPIEventGroup=${event.PAPIEventGroup}
event.PAPIEventId=${event.PAPIEventId}
event.PAPIEventStr=${event.PAPIEventStr}
event.PAPItimeStamp=${event.PAPItimeStamp}
event.PAPIObjectID_1=${event.PAPIObjectID_1}
event.PAPIObjectID_2=${event.PAPIObjectID_2}
event.PAPIObjectID_3=${event.PAPIObjectID_3}
event.PAPIObjectID_4=${event.PAPIObjectID_4}
event.PAPIpriority=${event.PAPIpriority}
event.PAPIAttr=${event.PAPIAttr}
event.PAPIDescr=${event.PAPIDescr}
event.PAPIImpact=${event.PAPIImpact}
event.PAPIImpactDescr=${event.PAPIImpactDescr}
event.PAPIDetails=${event.PAPIDetails}

Where:

• [data] is the mandatory name of the data section.
• ${event.PAPIID} is a numeric value specifying the current instance of the event.
• ${event.PAPIEventGroup} is a numeric value specifying the event's group.
• ${event.PAPIEventID} is the event identifier within the context of the event group.
  
  The combination of event group and event ID uniquely identify all Entuity event types
• ${event.PAPIEventStr} is the description of the event associated with the event identifier.
• ${event.PAPItimestamp} is the time the event occurred, represented as UTC (Coordinated Universal Time, i.e. the number of seconds since 1970-01-01 00:00:00
  GMT).
• ${event.PAPIObjectID_1}, ${event.PAPIObjectID_2}, ${event.PAPIObjectID_3} and ${event.PAPIObjectID_4} are internal values that indicate the origin of the event.
• ${event.PAPIpriority} is retained for backward compatibility.
• ${event.PAPIAttr} is an internal numeric attribute, not used for the integration.
• ${event.PAPIImpactDescr} lists entities likely to be affected by the event, e.g. hosts, VLANs and monitored applications.
• ${event.PAPIDescr} is a textual description of the managed object on which the event occurred, e.g. VLAN, device, module or port.
• ${event.PAPIDetails} is supplemental information on the particular event, e.g. actual values of network statistics which caused a threshold event.

Java Fork process:

forkevent communicates with the AR System servers through EventActionApplication. Each time EventActionApplication forwards data to arforward, it generates a new Fork process. As the process is created, arguments detailing the event are passed to arforward (the forked process). You can pass these arguments through start.

Once the data is sent, the process is closed. Each AR has its own Fork process.

To configure automatic AR generation on all events:

1. Open an Entuity client and create the View (e.g. "coreRouters") for use with the integration. Take care to include in that View only those object/event type combinations against which you would want automatic AR generation.
2. Amend entuity_home/etc/remedyforkevent.cfg to permit access to that View on your Entuity server, e.g.:
   

   [connection]
   username=JJones
   view=coreRouters

   
   This example forwards all events in the View called "coreRouters", with access being permitted to forkevent through the defined Entuity user account. By default, all events in the defined View are forwarded. To forward only specified events, apply a filter through sw_remedy_menu_def.cfg.
3. Amend the startup state of Remedy to normal. This will allow forkevent to run automatically each time Entuity starts. In the Entuity startup file startup_O/S_site_specific.cfg, amend the Remedy configuration to:
   

   S_site_specific.cfg) amend the Remedy configuration to:
   [remedy]
   state=normal
   type=command
   start=${ENTUITY_HOME}${FPS}integ${FPS}ForkEvent${FPS}forkevent
   ${ENTUITY_HOME}${FPS}etc${FPS}remedyforkevent.cfg pipe_remedy
   directory=${LOGDIR}
   is_critical=n

   
   The integration logging information is listed in EventActionApplication.log file. For more detail, set the log level to true in entuity_home/etc/RemedyForkEventLoggerConf.xml. This is valid only for the automatic integration.
4. Stop and restart Entuity.

To control which events result in automatic AR generation:

Which raised events result in the automatic creation of an AR is determined through a combination of Entuity Views and advanced action configuration.

1. Create a View, and specify the object and View filters on it.
2. Configure forkevent to use that View through the connection section of remedyforkevent.cfg:
   • By default, the event filter available with the advanced action uses wildcards (asterisks) for event group and event identifiers, allowing events of all types through to the AR System:
     

     [MenuItem Event_Menu1_ARSingleRemedyForkEvent_HD]
     .
     supportedEventTypes=*:*
     .

   • You can adjust the event filter to only forward specified events, e.g.:
     

     supportedEventTypes=512:7

     uniquely identifies the Network Outage, with 512 as its event group identifier and 7 as its event identifier.
     
     You can identify more than one event type, using commas to separate each event, e.g.:
     

     supportedEventTypes=1024:800,1024:802

     respectively identifies AP Host Count High and AP Host Count Low events.