Administer > Configure Incidents > Configure Management Events > Management Event form > Configure actions for a management event incident

Configure actions for a management event incident

You can configure actions to automatically run at any point in the incident lifecycle. For example, you might want to configure an action to occur when an incident of the type you are configuring is generated (Registered). When an incident is generated, you might want to automatically open a trouble ticket or send email or page your network operator. After the incident is Closed, you might want to automatically close the trouble ticket.

Note Your actions will not be executed until you enable the Actions configuration by either clicking Enable on the Actions tab or using the Actions → Enable Configuration option.

Note If the NNMi management server is running on a Windows operating system, NNMi runs each action that you configure using the Local System account. If the NNMi management server is running on a Linux operating system, NNMi runs each action that you configure using the bin user name.

You can configure actions for incidents generated from SNMP Trap Incidents, Syslog Messages Incidents and the NNMi Management Event Incidents. Any time an incident configuration changes, the action directory is rescanned and any Jython files are reloaded to the NNMi database.

Tip Copy any required Jython files to the NNMi actions directory before you configure an incident action. New or updated actions are loaded into NNMi only when an incident configuration is updated or created.

When the defined Incident Action runs, output is logged to the incidentActions.*.*.log file. To view the contents of the Actions log, use the Tools > Incident Actions Log menu option.

NNMi sets the default values described in the following table.

Action Server Properties
Property Description Value
numProcess Number of actions that can be run at one time. 10
numJythonThreads Number of threads the action server uses to run Jython scripts. 10
userName User name under which the action server runs. bin

To configure an automatic action for an incident: 

  1. Navigate to the Actions tab.

    1. From the workspace navigation panel, select the Configuration workspace.
    2. Expand the Incidents folder.
    3. Select Management Event Configurations.

    4. Do one of the following:

      • To create an incident configuration, click the  New icon, and continue.
      • To edit an incident configuration, select a row, click the Open icon, and continue.
      • To delete an incident configuration, select a row, and click the Delete icon.
    5. Select the Actions tab.
  2. From the Lifecycle Actions table toolbar, do one of the following:
    • To create an Action configuration, click the  New icon, and continue.
    • To edit an Action configuration, select a row, click the Open icon, and continue.
    • To delete an Action configuration, select a row, and click the  Delete icon.
  3. In the Lifecycle Transition Action Form (Management Events), provide the required information. 

  4. Click  Save and Close to save your changes and return to the previous form. 

    The next time the lifecycle changes, NNMi launches the action associated with the lifecycle for the incident of that type.

Lifecycle Transition Action form

Use this form to enter the command you want to run when an incident of the type you are configuring is at a particular Lifecycle State. For example, when an incident is generated (Registered), you might want to automatically open a trouble ticket or email or page your network operator.

Your actions will not be executed until you enable the Actions configuration by either clicking Enable on the Actions tab or using the Actions > Enable Configuration option.

To configure an action for an incidents:

  1. Navigate to the Lifecycle Transition Actions form:

    1. From the workspace navigation pane, select the Configuration workspace.
    2. Expand the Incidents folder.
    3. Select Management Event Configurations.
    4. Select the Actions tab.

    5. From the Lifecycle Transition Action table toolbar, do one of the following:

      • To create an Action configuration, click the New icon, and continue.
      • To edit an Action configuration, select a row, click the Open icon, and continue.
      • To delete an Action configuration, select a row, and click the  Delete icon.

  2. Make your configuration choices (see table).

    NNMi reloads the configuration information anytime the incident configuration is changed.

  3. Click  Save and Close to save your changes and return to the previous form. 
Create Action Attributes
Attribute Description
Lifecycle State Select a Lifecycle State from the drop-down menu.
Command Type

If you provided a Jython command, select Jython from the drop-down list.

If you are using an executable or bat file, select ScriptOrExecutable from the drop-down list.

Command

Enter one of the following:

  • A Jython method with the required parameters.
  • Executable command for the current operating system with the required parameters.

When entering a Command value, note the following:

  • Left or right bracket ([ ]) and backtick ( ` Unicode character: 0060 hex = 96 dec) characters are not permitted in the Command attribute. If you need these characters in your shell script, place them in a shell script file and reference that file from the Command attribute.
  • Windows only: Shell commands are not permitted in the Command attribute. To use shell commands, place them in a shell script file and reference that file from the Command attribute.
  • Use absolute paths to executables instead of relying on the PATH variable as it might not be set correctly.
  • Verify that you do not have two Jython methods with the same name. Otherwise, NNMi is not able to tell which is the correct method to load.

  • You can use the same Jython method for more than one incident configuration.

  • Jython (.py) files must reside in the following directory:

    All the functions defined in the Jython files that reside in this directory are also accessible by NNMi. The files are also executed by NNMi on startup.

    Windows:

    %NnmDataDir%\shared\nnm\actions

    Linux:

    $NnmDataDir/shared/nnm/actions

    /var/vols/itom/<nom_data_directory>/shared/nnm/actions

  • When using executable files, specify the absolute path to the executable command or make sure the directory in which the executable file resides is in your PATH environment variable.
  • NNMi provides a set of parameters that can pass attribute values from an incident configuration.

Configure a Payload filter for an action

The Payload Filter Editor enables you to create expressions that further refine the filters used to select the incidents that cause the configured action to run. Make sure to design any complex Payload Filters offline as a Boolean expression first. This method can help to minimize errors when entering your expressions using the Payload Filter editor.

To create a Payload Filter expression:

  1. Navigate to the Management Event Configuration form:

    1. From the workspace navigation panel, select the Configuration workspace.
    2. Expand the Incidents folder.
    3. Select Management Event Configurations.

    4. Do one of the following:

      1. To create an incident configuration, click the  New icon, and continue.
      2. To edit an incident configuration, select a row, click the  Open icon, and continue.
      3. To delete an incident configuration, select a row, and click the  Delete icon.
  2. Select the Actions tab.

  3. Do one of the following:

    1. To create a new configuration, click the   New icon.
    2. To edit an existing configuration, select a row, click the  Open icon, and continue.
  4. Select the Payload Filter tab.

  5. Define your Payload Filter.

    1. Plan out the logic needed for your Filter String.

    2. Use the buttons on the bottom half of the Additional Filters Editor to establish the logic structure.

      For example, to establish the following structure, click AND, then AND, and then OR:

      (( ) AND ( ))

    3. Now place your cursor in a location within the displayed Filter String, and use the top half of the filter editor to define the parameters of the highlighted filter requirement.

      For example, select a set of parentheses and use the Insert button to specify the filter requirement within those parentheses:

  6. Click  Save and Close.
  7. Click  Save and Close to save your changes and return to the previous form.

When creating a Payload Filter, note the following:

  • Payload Filter expressions for the like and not like operators use the syntax defined for java regular expressions (java.util.regex Pattern class)
  • You must use a ciaName that already exists in the trap or event you are configuring.
  • Each set of expressions associated with a Boolean Operator is treated as if it were enclosed in parentheses and evaluated together.
  • View the expression displayed under Filter String to see the logic of the expression as it is created.

  • The AND and OR Boolean Operators must contain at least two expressions as shown in the example below.

    The following example filters incidents on voltage state. Using this Payload Filter, you could then configure the Basics settings of the Enrichment Configuration to set the severity and message format to all incidents that return a state value of 4 or 5.

    OR

        ciaName = .1.3.6.1.4.1.9.9.13.1.2.1.7

         ciaValue = 4

        AND

          ciaName = .1.3.6.1.4.1.9.9.13.1.2.1.7

          ciaValue = 5

    NNMi evaluates the expression above as follows:

    (ciaName = .1.3.6.1.4.1.9.9.13.1.2.1.7 AND ciaValue = 4) OR (ciaName = .1.3.6.1.4.1.9.9.13.1.2.1.7 AND ciaValue = 5)

    NNMi finds all incidents with a varbind value of .1.3.6.1.4.1.9.9.13.1.2.1.7 and CIA value of 4 or 5.

    When you use ciaName and ciaValue in a Payload Filter, you must enter the ciaName and ciaValue as a pair as shown in the preceding example.

  • The placement of your cursor and the subsequent text that is selected is important when performing operations using the Payload Filter Editor. For example, you append to, replace, or change the indentation of the expression that is selected.
  • The placement of your cursor and the subsequent text that is selected is especially important when adding your Boolean operators.
Payload Filter Editor Settings
Attribute Description
Attribute

The attribute name on which NNMi searches. Filterable attributes include the following:

  • ciaName
  • ciaValue
  • sourceName

When you use ciaName and ciaValue in a Payload Filter, you must enter the ciaName and ciaValue as a pair. For example: (ciaName =.1.3.6.1.4.1.9.9.13.1.2.1.7 ) AND ( (ciaValue = 4) OR ( ciaValue = 5)) is not supported.

The sourceName value must be the name of the node as displayed on the node form and not the host name or management address.
Operator

Valid operators are described below.

  • = Finds all values equal to the value specified.

    Example: ciaName=.1.3.6.1.4.1.9.9.13.1.2.1.7 matches any incident that contains a varbind with the name value .1.3.6.1.4.1.9.9.13.1.2.1.7.

  • != Finds all values not equal to the value specified.

    Example: ciaName!=.1.3.6.1.4.1.9.9.13.1.2.1.7 matches any incident that contains a varbind with the name value other than 1.3.6.1.4.1.9.9.13.1.2.1.7.

  • < Finds all values less than the value specified.

    Example: ciaValue < 6 matches any incident that contains a varbind value less than 6.

  • <= Finds all values less than or equal to the value specified.

    Example: ciaValue <= 6 matches any incident that contains a varbind value less than or equal to 6.

  • > Finds all values greater than the value specified.

    Example: ciaValue > 4 matches any incident that contains a varbind value greater than 4.

  • >= Finds all values greater than or equal to the value specified.

    Example: ciaValue >= 4 matches any incident that contains a varbind with values greater than or equal to 4.

  • between Finds all traps or events that include a varbind value equal to and between the two values specified.

    Example: ciaValue between

    matches any incident that contains a varbind value equal to or greater than 1 and equal to or less than 4.

    As shown in the example, each value must be entered on a separate line.

  • in Finds any match to at least one value in a list of values.

    Example:

    ciaValue in

    matches any incident that contains a varbind value of either 4 or 5.

    As shown in the example, each value must be entered on a separate line.

    NNMi displays the list of attributes using comma-separated values enclosed in parentheses, for example (4, 5). However, the comma-separated list is used only for display purposes. The actual delimiter is the new line.

  • is not null Finds all non-blank values.

    Example: ciaValue is not null matches any incident with varbind values.

  • is null Finds all blank values.

    Example: ciaValue is null matches any incident with no varbind values.

  • like Finds matches using wildcard characters. Click here for more information about using wildcard characters.

    The period asterisk (.*) characters mean any number of characters of any type at this location.

    The period (.) character means any single character of any type at this location.

    To include literal string values in the Value attribute, enclose the string value in \Q<literal_value>\E as shown in the Examples listed below.

    Examples:

    ciaName like  \Q .1.3.6.1.4.1.9.9\E.* finds all traps or events that contain varbind names that begin with .1.3.6.1.4.1.9.9 and (optionally) end with any number of characters.

    ciaValue like .*Chicago.* finds all traps or events that contain a varbind value that includes the string Chicago.

  • not between Finds all values except those between the two values specified.

    Example: ciaValue not between 5 8 matches an incident that contains a varbind with the values less than 5 or greater than 8.

  • not in Finds all values except those included in the list of values.

    Example:

    ciaValue not in

    matches any incident that contains a varbind with values other than 1 and 2.

    As shown in the example, each value must be entered on a separate line.

    NNMi dsisplays the list of attributes using comma-separated values enclosed in parentheses, for example, (1, 2). However, the comma-separated list is used only for display purposes. The actual delimiter is the new line.

  • not like Finds all that do not have the values specified (using wildcard strings).

    The period asterisk (.*) characters mean any number of characters of any type at this location.

    The period (.) character means any single character of any type at this location.

    To include literal string values in the Value attribute, enclose the string value in \Q<literal_value>\E as shown in the Examples listed below.

    Example:

    ciaName not like \Q.1.3.6.1.4.1.9.9\E.* matches any incident that contains a varbind name value that does not begin with .1.3.6.1.4.1.9.9.

    ciaValue not like .*Chicago.* finds all traps or events that do not contain a varbind value that includes the string Chicago.
Value

The value for which you want NNMi to search.

Note the following:

  • The values you enter are case sensitive.
  • NNMi displays a variable number of value fields depending on the Operator selected. For example, the between Operator causes two value fields to be displayed.
  • The between, in and not in operators require that each value be entered on a separate line.
Payload Filter Editor Buttons
Button Description
Append Appends the current expression (Attribute, Operator, and Value) to the selected expression already included in the filter string.
Insert Inserts the current expression (Attribute, Operator, and Value) in front of the cursor location within the Filter String.
Replace Replaces the selected expression with the expression displayed in the Attribute, Operator, and Value fields.
AND

Inserts the AND Boolean Operator in the selected cursor location.

View the expression displayed under Filter String to see the logic of the expression as it is created.
OR

Inserts the OR Boolean Operator in the current cursor location.

View the expression displayed under Filter String to see the logic of the expression as it is created.
NOT

Can be used in any part of the Filter String to specify that NNMi should exclude interfaces with values that pass the expression that immediately follows the NOT.

For example, when evaluating the following expression, NNMi includes interfaces with (interface description) ifDesc containing VLAN, and excludes any Interfaces that have VLAN10 for the (interface name) ifName value:

(ifDesc like VLAN AND NOT (ifName=VLAN10))

View the expression displayed under Filter String to see the logic of the expression as it is created.
EXISTS

Used for filters that include Capabilities or Custom Attribute names and values in the Filer String.

Indicates that you want NNMi to consider interfaces that have Capabilities or Custom Attributes when evaluating the Filter String.

Tip When creating complex Filter Strings that include customAttrName and customAttrValue pairs as one component of an "or" statement, to prevent NNMi from excluding Nodes that have zero Custom Attributes, use EXISTS or NOT EXISTS criteria for the customAttrName and customAttrValue pair definitions.

Otherwise Nodes that do not have any Custom Attributes are automatically excluded even if they have values that pass other aspects of your filter.

ou include Capabilities or Custom Attribute names and values in the Filer String, but do not use EXISTS or NOT EXISTS, NNMi excludes from its search interfaces that do not include Capabilities or Custom Attributes.

For example, when evaluating the following Filter String, NNMi includes interfaces with (interface description) ifDesc containing VLAN, as well as any Interfaces Custom Attribute Role value is LAN Connection to Oracle Server:

(ifDesc like VLAN OR EXISTS((customAttrName=Role AND customAttrValue=LAN Connection to Oracle Server)))

View the expression displayed under Filter String to see the logic of the expression as it is created.
NOT EXISTS

Used for filters that include Capabilities or Custom Attribute names and values in the Filer String. Indicates that you want NNMi to consider interfaces that do not have any Capabilities or Custom Attributes when evaluating the Filter String, but exclude the interfaces that match the expression that follows the NOT EXISTS.

Tip When creating complex Filter Strings that include customAttrName and customAttrValue pairs as one component of an "or" statement, to prevent NNMi from excluding Nodes that have zero Custom Attributes, use EXISTS or NOT EXISTS criteria for the customAttrName and customAttrValue pair definitions.

Otherwise Nodes that do not have any Custom Attributes are automatically excluded even if they have values that pass other aspects of your filter.

For example, when evaluating the following expression, NNMi includes interfaces with (interface description) ifDesc containing VLAN, and excludes any Interfaces that have the Custom Attribute Role and that Role value is LAN Connection to Oracle Server:

(ifDesc like VLAN OR NOT EXISTS((customAttrName=Role AND customAttrValue=LAN Connection to Oracle Server)))

View the expression displayed under Filter String to see the logic of the expression as it is created.

Delete

Deletes the selected expression.

If the Boolean Operator is selected, the Payload Filter Editor deletes all expressions associated with the Boolean Operator.

Valid parameters for configuring incident actions

When configuring incident actions, consider using incident information as part of the action. NNMi provides the following parameter values. Use these parameters as variables in your Jython or executable files.

Tip If a value is not stored for a parameter, it is returned as “null”.

Valid Parameters Visible From an Incident's Form
Parameter Value Description
$category, $cat Value of the Category attribute in the Incident form.
$count, $cnt Value representing the number of Custom Incident Attributes that appear in the Incident form.
$family, $fam Value from the Family attribute in the Incident form.
$firstOccurrenceTime, $fot Value from the First Occurrence Time attribute in the incident form.
$lastOccurrenceTime, $lot Value from the Last Occurrence Time attribute in the incident form.
$lifecycleState, $lcs Value from the Lifecycle State attribute in the Incident form.
$name Value of the Name attribute from the incident configuration.
$nature, $nat Value from the Nature attribute in the Incident form.
$origin, $ori Value from the Origin attribute in the Incident form.
$originOccurrenceTime, $oot Value from the Origin Occurrence Time attribute in the incident form.
$priority, $pri Value from the Priority attribute in the Incident form.
$severity, $sev Value of the Severity attribute of the Incident form.
Valid Parameters Visible from a Node Form
Parameter Value Description
$managementAddress, $mga Value from the Management Address attribute of the incident's source Node's form or SNMP Agent form.
$otherSideOfConnectionManagementAddress, $oma If the incident's Source Node is part of a Layer 2 Connection, this attribute is the value of the Management Address of a node on the other side of the Layer 2 Connection.
$sourceNodeLongName, $sln The fully-qualified DNS name as displayed in the Hostname attribute of the incident's source Node's form.
$sourceNodeName, $snn Value from the Name attribute of the incident's source Node's form.
$sysContact, $sct Value from the System Contact attribute of the incident's source Node form: General tab.
$sysLocation, $slc Value from the System Location attribute of the incident's source Node form: General tab.
Valid Parameters Visible from an Interface Form
Parameter Value Description
$ifAlias, $ifa Value from the IfAlias attribute for the interface that is the incident's source object.
$ifConfigDupSetting, $icd Configured Duplex Setting on the port associated with the interface that is the incident's source object.
$ifDesc, $idc Value from the ifDesc attribute for the interface that is the incident's source object.
$ifIndex, $idx Value from the ifIndex attribute for the interface that is the incident's source object.
$ifIpAddr, $iia IP Address values associated with the interface that is the incident's source object. If multiple IPaddresses are associated with the interface, this parameter returns a comma-separated list.
$ifName, $ifn Value from the ifName attribute for the interface that is the incident's source object.
$ifPhysAddr, $ipa Value from the Physical Address attribute for the interface that is the incident's source object.
$ifSpeed, $isp Value from the ifSpeed attribute for the interface that is the incident's souce object.
$ifType, $itp Value from the ifType attribute for the interface that is the incident's souce object.
Valid Parameters Visible from a Layer 2 Connection Form
Parameter Value Description
$otherSideOfConnectionConfigDupSetting, $ocd If the incident's source Node is part of a Layer 2 Connection, this parameter contains the Configured Duplex Setting on the port associated with the interface on the other side of the connection.
$otherSideOfConnectionIfAlias, $oia If the incident's Source Node is part of a Layer 2 Connection, this parameter is the value of the ifAlias of one of the interfaces on the other side of the Layer 2 Connection.
$otherSideOfConnectionIfDesc, $odc If the incident's Source Node is part of a Layer 2 Connection, this parameter contains the ifDescr attribute value for the interface on the other side of the Layer 2 Connection.
$otherSideOfConnectionIfIndex, $odx If the incident's Source Node is part of a Layer 2 Connection, this parameter contains the ifIndex attribute value for the interface on the other side of the connection.
$otherSideOfConnectionIfName, $ofn If the incident's Source Node is part of a Layer 2 Connection, this parameter contains the ifName attribute value for the interface on the other side of the connection.
Valid Parameters Visible from a VLAN Form
Parameter Value Description
$impVlanIds, $ivi Value from the VLAN Id attribute associated with the interface that is the incident's source object. To access this information from an interface form, navigate to the VLAN Port tab and open the form for the VLAN of interest. If the interface is part of more than one VLAN, this parameter returns a comma-separated list.
$impVlanNames, $ivn Value from the Global VLAN Name attribute associated with the interface that is the incident's source object. To access this information from a Node form or Interface form, navigate to the VLAN Ports tab. If the node or interface is part of more than one VLAN, this parameter returns a comma-separated list.
Valid Parameters Not Visible From a Form
Parameter Value Description
$id Unique Object Identifier attribute value for the incident (unique across the entire NNMi Database).
$firstOccurrenceTimeMs, $fms Value from the First Occurrence Time attribute in the incident form, converted to millseconds (measured since January 1, 1970, 00:00:00 GMT - Greenwich Mean Time).
$lastOccurrenceTimeMs, $lms Value from the Last Occurrence Time attribute in the incident form, converted to millseconds (measured since January 1, 1970, 00:00:00 GMT - Greenwich Mean Time).
$messageFormat, $msg Valid for Incident actions only. Message text displayed for an incident when this parameter is included as an argument to an incident action.
$oid Value of the unique object identifier (oid) for the incident configuration that originated from either an SNMP Trap, Syslog Message or Management Event.
$otherSideOfConnection, $osc

If the incident's Source Node is part of a Layer 2 Connection, this attribute is the following combination of values for the node and one of its interfaces on the other side of the Layer 2 Connection:

The fully-qualified DNS name of the node appended with the interface Name in the following format: <fully-qualified DNS name>[interface_name]
$originOccurrenceTimeMs, $oms Value from the Origin Occurrence Time attribute in the incident form, converted to millseconds (measured since January 1, 1970, 00:00:00 GMT - Greenwich Mean Time).
$sourceNodeUuid, $snu Universally Unique Object Identifier attribute value of the source node object for the incident (unique across all databases). This identifier distinguishes the source node object instance from all other node objects.
$sourceObjectClass, $soc Value of the object class for the object you want to include. Use this parameter to request more details of a class of objects through a web service. Examples of object classes include: com.hp.ov.nms.model.core.Interface and com.hp.ov.nms.model.snmp.SnmpAgent.
$sourceObjectName, $son Value from the Name attribute of the source object. For example, an interface object is named according to the MIB ifName. Each ifName varies according to the vendor's conventions. Using the name 4/1 as an example, 4 represents the board number and 1 represents the port number.
$sourceObjectUuid, $sou Universally Unique Object Identifier attribute value of the source object for the incident (unique across all databases). This identifier distinguishes the source object instance from all other similar object instances..
$uuid Universally Unique Object Identifier attribute value of the incident (unique across all databases). This identifier distinguishes the incident object instance from all other incident objects.
Valid Parameters Established in Custom Incident Attributes
Parameter Value Description
$<position_number>

Value of the custom incident attribute (CIA) position number for any CIA that originated from a varbind or was added by NNMi. For example, to indicate you want to use the varbind in position 1, enter: $1

NNMi stores varbind values as Custom Incident Attributes. If you know the varbind position number, use this parameter.
$<CIA_name>

Value of the name that is used for the custom incident attribute. For example, $mycompany.mycia. NNMi provides CIA values for configuring Management Events.
$<CIA_oid> Value of the object identifier for any custom incident attribute that originated as a varbind. For example, $.1.3.6.1.6.3.1.1.5.1. Use this parameter when you are not certain of a custom incident attribute (varbind) position number.
$* Used to indicate you want all of the custom incident attribute values originating as varbinds, to be passed to the action configuration. Each varbind is returned in the following format: $<CIA_name>:<CIA_value> in which the custom incident attribute name appears followed by the custom incident attribute value.

The function described in the following table replaces the specified numeric value with the associated text value stored in the CIA.

Note The associated MIB must have been loaded using the nnmloadmib.ovpl command.

Functions to Generate Values Within Incident Messages
Function Description
$text($<position_number>)

The <position_number> argument specifies the numeric value of the custom incident attribute (CIA) position number for any CIA that originated from a varbind or was added by NNMi. For example, to indicate you want to use the varbind in position 1, enter: $1.

After the function runs, NNMi replaces the numeric value with the text value stored in the CIA.

If a text value is not available, NNMi returns the numeric value.
$text($<CIA_oid>)

The <CIA_oid> argument specifies the object identifier for any custom incident attribute that originated as a varbind. For example, $.1.3.6.1.6.3.1.1.5.1. Use this argument to the $text function when you are not certain of a custom incident attribute (varbind) position number.

After the function runs, NNMi replaces the numeric value with the text value stored in the CIA.

If a text value is not available, NNMi returns the following message as the value:
<CIA <OID> with value <value> was not found within the mib cache

Related topics

Send Help Center feedback