Event Processing Interface scripts

• Scripts are executed in the following working directory on the OMi gateway server:

  hpbsm_opr-scripting-host

• Logging information is written to the following log file:

  <OMi_HOME>/log/opr-scripting-host/opr-scripting-host.log

EPI scripts are triggered automatically every time the scripting host process is executed. You can configure the location in the event pipeline process flow where the script is executed when you configure the script in the OMi Console. You can choose several locations, as visualized in the figure below:

1. Before CI/ETI Resolution: The script is executed when the event enters the event pipeline, before CI/ETI resolution.

2. After CI/ETI Resolution: The script is executed immediately after CI/ETI resolution

3. Before Storing Events: The script is executed after all event processing has taken place, but before the event is stored in

   the database.

4. After Storing Events: The script is executed after the event has been stored in the database. All scripts configured in this location are executed in read-only mode.

Scripts are stored in the database, and can be accessed from the OMi Console.

To configure an event forwarding script and activate it:

1. In OMi, navigate to Event Processing Customizations:

   Administration > Event Processing > Automation > Event Processing Customizations

   Alternatively, click Event Processing Customizations.

   The Event Processing Customizations screen looks similar to the figure below.

   

   The screen contains three panes:

   1. EPI Steps 

      This pane lists the possible locations in the event pipeline where scripted actions can be added to the event processing. The listed locations correspond to the locations shown in the figure above.

   2. Event Processing Scripts ‚

      This pane lists all scripts that have been configured for the selected location. When you select a location in the EPI Steps pane, a list of scripts is shown with gray or black text. Scripts shown in gray ƒ are not active, scripts in black „ are.

   3. Details

      This pane shows the properties of the actual script, including an editor field with the script code †.

   By default, some sample scripts and placeholders are present in the database. HPE recommends using the sample classes provided as a starting point when writing a new script to ensure that all required methods are available.

2. After your script is finished activate it by either selecting it and clicking the  Activate Item button, or by right-clicking it and selecting Activate Item. The script is now executed every time the event pipeline is processed.

When writing an EPI script, you must apply the following rules:

1. A script must be contained in a class.

   1. You can choose your own name for the class. The name of the class(es) you configure are added to the Event Processing Scripts pane in the OMi administration console.

   2. The class does not inherit any properties or methods.

   Example of a class declaration:
   class EpiBeforeStoringEvents{ ... }

2. If your script class includes public init() and destroy() methods, these methods are called when the script class is instantiated and destroyed, respectively. You can use these methods to implement customized initialization and clean-up actions that should be called only once (see also Best practices).

3. The script class must have a public method named process(eventList). This method is called by the platform when the script is executed. The argument eventList receives an array of Event objects you can step through using a for statement (see the example in this section).

4. If a script class has a public method named getInternalScriptError() and the method returns a value of 10 or higher, the script is skipped by the platform service executing the script. To use this feature, insert the following code:
   int internalScriptError = 0;
def int getInternalScriptError() { return internalScriptError; }
def setInternalScriptError() { internalScriptError++; }
   This code causes the member variable internalScriptError, which holds the script error level, to be initialized to 0, and enables the programmer to increase the error level by calling the setInternalScriptError() method whenever an error occurs.

5. You may include any other methods, properties, and members as needed.

To minimize the impact of EPI scripts on the performance of OMi processing, consider the following aspects:

• Be aware of the number of scripts loaded at any one time. Loading a script introduces overhead until the scripts is unloaded, so loading too many scripts at any one time could lead to performance problems.

• Use background threads and cache information where possible (see also Best practices).

• If you need data from the RTSM (or any other external files or databases), open the connection to the RTSM in the init() method and close the connect in the destroy() method (see also Best practices).

• Minimize the processing time required to execute the script's process() method. Especially EPI scripts should be written for absolute speed. See also Best practices.

• EPI scripts will have a negative impact on the overall event processing if they experience problems with external resources such as DNS availability, network availability, and slow file access, especially if the process() method uses those resources.

• Access the RTSM using its JAVA API (see also Best practices).

• You can configure the order in which scripts are executed when you configure the script in the OMi Console. Scripts can be moved up or down in the sequence using the up and down icons in the Scripts Panel toolbar. By default, scripts are marked read/write; use the read-only icon to mark a script read-only. Whether scripts are read-write or read-only has the following impact on when they are executed relative to other scripts:

  • Scripts that need to modify events need read/write access to the database. They are marked read/write and are executed in the order they are configured to avoid potential conflicts.

  • Scripts in read-only mode may be executed in parallel (asynchronously) with read/write scripts.

  This means that read-only scripts have less impact on event throughput than read-write scripts. Therefore, mark scripts read-only wherever possible. To mark a script read/write, use the read/write icon.

  Note Scripts located at the After Storing Events process step are always executed in read-only mode, because events stored in the database can no longer be modified by an EPI script.

• Scripts using an event filter may have slightly more impact on overall event throughput. Balance the use of filters against the number of events you would have to load without filtering.

• You can configure the timeout value for each script in the OMi Console.

  • Scripts running in read/write mode (synchronously) abort when the timeout time has elapsed, and any changes the script made to events are rolled back.

  • Scripts running in read-only mode (asynchronously) simply abort when the timeout time has elapsed.

  HPE recommends configuring a timeout for EPI scripts to minimize potential impact of any single script experiencing problems on the overall OMi pipeline, thereby minimizing the risk of process disruptions.

  Configuring a timeout is especially important for scripts using external resources. The best timeout value must be ascertained by testing the script under conditions where access to external resources the script depends on are problematic. When testing scripts, look at the following log file to see how long each script is taking to execute for each event it receives:

• Do not store too much data in memory (see also JVM statistics).

• Release resources when they are no longer needed, and watch for memory leaks during debugging.

• Check the validity of resource handles and reconnect is necessary (see also Best practices).

The following sample script applies to the hypothetical situation where critical events are escalated and managed in an OMi-external escalation database. The script retrieves the owner of escalated events from the escalation database and adds it to the OMi event information.

import com.hp.opr.api.scripting.Event;
import external.api.scripting.dataBase;

class actionOnStatus
    /* A script must always be declared as a class.
     * The name of the script class is the name to be used as the name of
     * the Event Processing Script in the OMi Adminstration console. */
{
    int internalScriptError = 0;
                    // Note: The EPI server does not execute scripts
                    // if their getInternalScriptError method returns
                    // a value of 10 or higher.
    def int getInternalScriptError()
    { return internalScriptError; }

    def setInternalScriptError()
                    // Use this method to increment the internalScriptError.
    { internalScriptError++; }

    Database externalDB;
                    // Handle to an external database
                    // containing the data used to
                    // enrich events, in this case
                    // information about an escalation
                    // process.
    def connectionString = "MyCloud,MyUsername,MyPwd";


    def init()
    {

        // Actions to be taken when the Groovy script is compiled,
        // which happens once, when the EPI is activated.
        externalDB = connectDB(connectionString);
        if(!externalDB)
        {
            throwDatabaseException(
                "Could not connect to external dastabase"
                + " with connection string "
                + connectionString + "."
            );
            setInternalScriptError();
        }

    }

    def destroy()
    {
        // Actions to be done before destroying the script cache.
        externalDB.disconnect()
    }


    /* The process() method is called every time the EPI server processes
     * the event pipeline.
     *
     * In this example the process() method retrieves the escalation owner
     * of the related CI for all critical events in the pipeline from an
     * external database, and uses the information to set the event's OmUser
     * property. */

    def process(eventList)
                    // The eventList argument passes an array containing
                    // the events in the event pipeline.
    {
        try
        {
            for( Event in eventList )
            {
                String stringOmUser = "";
                String stringQuery = "";

                int eventSeverity = Event.getSeverity();
                if( eventSeverity == CRITICAL)
                {
                    def RecordSet rsEventInfo;

                    stringQuery = "SELECT escalationOwner AS eo "
                        + "FROM servers WHERE hostname = "
                        + """" + Event.getRelatedCiHint() + """ "
                        + "SORT BY contactPriority ASC";

                    rsEventInfo = externalDB.Open(StringQuery);
                    if( rsEventInfo.RecordCount > 0 )
                    {
                        stringOmUser =
                        "Primary escalation owner: "
                        + rsEventInfo.Fields("eo");
                    } else {
                        stringOmUser =
                        "No escalation owner for CI: "
                        + Event.getRelatedCiHint();
                    }

                    setOmUser(stringomUser);
                }
                // Anything else that needs to be done when this
                // event is processed goes here.
            }
        }

        catch( DatabaseException e )
        {
            setInternalScriptError();

            // Anything else that needs to be done when this
            // exception is thrown goes here.
        }


        finally
        {
            // Actions to be done after all events are processed.
            // In this example, nothing is needed here.
        }

}