External instruction retrieval 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

When the script execution is triggered by OMi, the event is passed into the script in a read-only state. The script can access all properties of the event including the specified instruction parameters, such as the instruction interface name (property 'event.instructionInterfaceName') and the parameter string (property 'event.instructionParameterString'). As a parameter, you can enter any option that you want to pass to the external program generating the instruction text, for example a policy variable or a policy parameter configured in the policy template.

The Instruction Available flag indicates whether the instructions are available for the event (the  icon in the I column for the selected event is displayed). This property is set to true at the time the event is created and stored in the database if the corresponding message from the agent (received on the OMi server and converted to the event) contains one of the following:

• The UUID of the instruction text that was specified in the policy

• The name of an instruction text interface to be used for the instruction text retrieval
  

Additionally, before the events are loaded into the Event Browser, OMi evaluates all active external instruction text interface definitions and checks whether their event filters match the event. If at least one event filter matches, the Instruction Available event flag is also set to true.

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 possible to retrieve the instruction text from different sources.

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

  To facilitate the event filtering, you can use the Instruction Interface Name and Instruction Parameter String Advanced Filter elements. This way, you limit the set of events displayed in the Event Browser to those with the specified instruction interface and parameter string. For more information about event filters, see Event Filters.

• By creating multiple event filters and mappings to Groovy scripts. The first event filter that matches will call the mapped Groovy script. If you choose this alternative, define event filters so that they do not match the same set of events.

  Note OMi always chooses the first event-matching filter. As it is not possible to define the order in which event filters are evaluated, you must only define disjunct event filters, that is, the event filters that match different sets of events.

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

To configure an instruction retrieval script:

1. Navigate to the External Instructions manager:

   Administration > Operations Console > External Instructions

   Alternatively, click External Instructions.

   The screen contains two panes:

   1. Scripts

      This pane lists the configured scripts. Active scripts are shown in black,inactive scripts in gray.

   2. Details

      This pane shows general and advanced properties of the selected script, including the scripts themselves.

2. Use the toolbar in the Scripts pane if you want to:

   • Edit an existing script. Click  Edit Item to open the script wizard, and then click the Script tab to access the script for editing.

   • Configure a new script. Click  New Item to open the script wizard. Enter the script and some information about it, such as a name and description. The wizard provides a skeleton for the script class, which you can use as a starting point.

   • Activate/deactivate a script by clicking  Activate Item or  Deactivate Item .

The event, including the related instructions, can be viewed in the OMi Event Browser. The instructions are displayed on the Instructions tab in the Event Details pane.

The Groovy script returns the output in the plain text or the HTML format. If the instruction text contains URLs, they are automatically converted into hyperlinks. The URLs starting with http://, https://, ftp://, fttps://, telnet://, and mailto: URI scheme names are supported. Note that you can add URLs of external websites, support sites, documentation repositories, troubleshooting information, and so on.

You can also type the address of any website that begins with www.

In the Event Browser, when you click the hyperlink, a new window opens with the page that was returned by the script.

OMi delivers a predefined content pack containing a sample instruction retrieval script and a filter for external instruction interfaces. A sample policy is included as well. You can use this initial script as a basis for developing customized scripts to better suit your business needs. For more information on content packs, see Content Packs.

This section provides two instruction retrieval Groovy scrip samples.

A sample instruction retrieval Groovy script:

import com.hp.opr.api.scripting.Event

class GroovyScriptSkeleton
{
  // called before the method "getInstructions" is called
  def init()
  {}
  // called after the method "getInstructions" is called
  def destroy()
  {}
  // This method gets as parameter the event for which instruction text should be retrieved and
  // returns the instruction text that is displayed in the event browser.
  def getInstruction(Event event)
  {
    if ("iti" == event.instructionInterfaceName)
    {
      // the command to execute; it gets the parameter string (as send by the agent) as argument
      // so, if the agent sends the name of the agent system, this command will ping the agent system
      // and the output of the ping command is returned as instruction text
      def command = "ping -n 1 " + event.instructionParameterString
      def proc = command.execute() // execute the command
      proc.waitForOrKill(3000)     // wait for 5sec before time-out
      if (proc.exitValue() == 0)
        return "ping of node '" + event.instructionParameterString + "': " + proc.in.text
      else
      { 
        if (event.instructionInterfaceName == null)
          return "No instructions are available for event with ID '" + event.id + "'."
        else
          return "Cannot get instructions for interface '" + event.instructionInterfaceName + "'."
      }
    }
  }
  // This method gets as parameter the list of events for which instruction text should be retrieved.
  // The instruction text for all events is returned as map with the ID of the event as key and the instruction text for this event as value.
  def getInstructions(List<Event> events)  
  {
    events.collectEntries { event ->
      [ event.id, getInstruction(event) ]
    }
  }
}	
								

A sample instruction retrieval Groovy script with the HTML output:

import com.hp.opr.api.scripting.Event

class GroovyScriptSkeleton
{
  def init()
  {}
  
  def destroy()
  {}
  
  def getInstruction(Event event)
  {
    if ("iti" == event.instructionInterfaceName)
    {
      // add your code to retrieve the instruction text from an external source
      return """<html><body><h1>My First Heading</h1><p>My first paragraph.</p><a href="http://www.google.com">This is a link</a>
      </body></html>"""
    }
    else
    {
      return "Cannot get instruction text for interface '" + event.instructionInterfaceName + "'."
    }
  }
    
  def getInstructions(List<Event> events)
  {
    events.collectEntries { event ->
      [ event.id, getInstruction(event) ]
    }	
  } 
}
					

Although the package com.hp.opr.api.scripting.Event generally allows changes on events (for example AddCustomAttribute("foo","bar"), the events cannot be updated at this point, so no changes are possible.