External Instructions

An external instruction interface enables you to utilize an external application to present the event instructions to an operator.

To retrieve the instructions from external instruction interfaces, in OMi, you must create and activate a Groovy script that calls the instruction interface and retrieves the instruction text for the specified event. In the script, you must define the command that will be called to retrieve the instruction text from an external source.

Next, on the Rules > Instructions tab of the Policy Editor, you must set the options for external instructions in the Type, Interface name, and Parameters fields. Once the policy is deployed and the specified event containing or referencing external instructions occurs, the Groovy script is executed. The event-related instructions can be viewed in the Event Browser (the instructions are displayed on the Instructions tab in the Event Details pane and are retrieved when you select the event and click the Instructions tab in the Event Details pane).

To retrieve the instructions from external instruction interfaces configured in OM for Linux or Windows, consider one of the following scenarios:

• You configured the event forwarding for the events originating on OM. In this case, on the OMi server, you must create an instruction retrieval Groovy script and provide the mapping to the event filter. When the specified event containing external instructions occurs, the instruction retrieval Groovy script is executed. The event instructions can then be viewed in the Event Browser.

• You migrated the policies from OM to OMi. If a link to an external instruction interface is defined in the OM policy, after the policy has been imported into OMi, the name of the external instruction interface and the parameter string appear in the Interface Name and Parameters fields of the Rules > Instructions tab in the Policy Editor. Check the values and make sure they meet your requirements. Then, create an instruction retrieval Groovy script, provide the mapping to the event filter, and deploy the policy to a node. The execution of the instruction retrieval Groovy script is triggered by the occurrence of the specified event containing external instructions.

  Note If the instruction text associated with an OM event was added directly without using an external instruction text interface, it is displayed in the Instruction Text field of the Rules > Instructions tab in the Policy Editor after the policy has been imported into OMi. Instructions are presented to an operator upon the occurrence of the specified event and are displayed in the Event Browser.

On the OMi server, you must define a Groovy script and an event filter matching the event(s) for which the script will be executed to retrieve the instruction text. Once the script execution is triggered by OMi, the event is passed to the script. The script can access all properties of the event including specified instruction parameters, such as the instruction interface name (property 'event.instructionInterfaceName') and the parameter string (property 'event.instructionParameterString'). These properties are used by the script to evaluate whether the instruction text can be retrieved and determine an external source from which the instruction text will be received.

The mapping to an instruction text interface can be achieved in one of the following ways:

• By creating one event filter that matches everything and defining one mapping from this event filter to a single Groovy script. Depending on the instruction interface name of the event that is passed to the script, it is also possible to retrieve the instruction text from multiple sources.

  Tip To avoid generating a high number of events having the Instruction Available property set to true (the  icon in the I column for the selected event is displayed) but containing no actual instructions, define the event filter so that it only matches the events for which the instruction text is available.

• By creating multiple event filters and mappings to Groovy scripts. The first event filter that matches will call the mapped Groovy script. As it is not possible to define the order in which event filters are evaluated, you should only define disjunct event filters, that is, the event filters that do not match the same set of events.

For more information on Groovy scripts and a sample of an instruction retrieval Groovy script, see Groovy scripts.

This task describes how to create a mapping from an event filter to an instruction retrieval Groovy script.

1. Click New or to open the Create External Instruction screen.

   The button is displayed only when you launch the External Instructions screen (Administration > Operations Console > External Instructions). If you are already on the External Instructions screen, click New to open the Create External Instruction screen.

2. In the General section, enter a display name, and an optional description for the script. Select Activate after save if you want to make the script active immediately (this option is selected by default). You can also activate the script later by clicking Activate.

3. In the Condition section, select an event filter for the instruction retrieval Groovy script from the Event Filter drop-down list. The filter determines which events will be considered in the mapping operation. If an event filter matches, OMi executes the specified Groovy script to retrieve the external instruction text.

   If no filter is configured, select an event filter from the drop-down list. You can create a new filter or edit an existing one. For information about creating filters, see How to Define Event Filters.

4. In the Properties section, click to add and order any JAR files required by the script (optional).

   The ordering of the JAR files is used by the class path during execution. For example:

   JAR file A contains a class x.y.z.

   JAR file B contains a class x.y.z.

   The ordering of the JAR files A and B dictates which class of which JAR file is loaded.

   Note The maximum JAR file size that you can upload is determined by Max file upload size in KB infrastructure setting (Infrastructure Settings > Foundations > Security > Security - File upload). For more information about this setting, see the online help.

   Enter a timeout value for the script in the Timeout field. If the script execution does not complete within the specified time, the script is ignored. You can uncheck the Ignore the script if not completed after check box, if you do not want to set timeout for the script.

5. Enter the text of the instruction retrieval Groovy script in the Script field.

   For information about creating Groovy scripts, see Groovy scripts.

   Note Maximum supported script length is 250,000 characters.

   Click Create.

   Once the Groovy script is created, it appears in the list of scripts in the left pane. If the specified conditions match, the script is executed with the specified parameters to get the instruction text from the external interface.

   You can click to activate the script and to deactivate the script. Alternatively, use the opr-script command-line interface to enable or disable a script. For more information, see opr-script Command-Line Interface in the OMi Extensibility Guide.

   Note Groovy scripts for retrieving external instructions can be defined in content packs and can be imported/exported using the Content Manager.