Integrate external event processes: FAQs

• For information about the event forwarding and synchronization process, see Forward events and synchronize event changes.
• For information about the Event Synchronization Web Service, see Event Synchronization Web Service interface.
• For information about integrations using Groovy scripts, see Integrate external event processes using Groovy scripts.
• For an introduction to using Groovy scripts, see Groovy scripts.

Yes. You can find the Javadoc here:

<OMi_HOME>/opr/api/doc/opr-external-api-javadoc.zip

Yes. You can find the schema here:

<OMi_HOME>/opr/api/schema/OprDataModel.xsd

If you integrate an external application using a Groovy script, you most likely do not need the OprEvent schema. The schema is mainly needed if you intend your integration to communicate directly with the Event Synchronization Web Service endpoints using OprEvent and OprEventChange objects with no intervention by a Groovy script. For example, if you implement a REST web service that will accept the HTTP POST method call of an OprEvent object (as described in the schema), and a REST client that either performs HTTP POST methods calls of OprEventChange objects, or performs HTTP PUT method calls for OprEvent objects to submit those objects with changes to the Event Synchronization Web Service. In this case, the connected server would be configured for a web service integration and not a Groovy script integration.

Additionally, if your client or service is written in Java, you can directly use the Java Architecture XML Binding (JAXB) annotated objects in the opr-external-api.jar file to marshal and unmarshal the XML. Only if you are programming in a different language should you need to use the schema directly.

No. The Event Synchronization Web Service is a simple REST-based web service. In general, REST-based web services do not have a WSDL.

A good place to start is the following Wikipedia entry:

http://en.wikipedia.org/wiki/Representational_State_Transfer

Use the Apache Wink toolkit, which you can get here:

http://incubator.apache.org/wink/index.html

Yes. The <OMi_HOME>/lib/opr-external-api.jar file contains JAXB annotated classes. If you are programming in Java, you can use these classes directly instead of generating classes from the schema. See the Javadoc API Documentation for details about the classes provided.

Yes. Take a look at the LogfileAdatper sample located here:

1. Open the Connected Servers manager:

   Administration > Setup and Maintenance > Connected Servers

   Alternatively, click Connected Servers.

2. In the Connected Servers pane, open the Event Forwarding Scripts Configuration dialog box.

3. Open the sample.LogfileAdatper Groovy script.

This is a sample Groovy script adapter that accepts forward requests and writes them to a log file.

When configuring this adapter, configure the connected server with the following parameters:

• node - localhost (do not use the DNS name here)
• port - 80 for standard http, 443 if TLS is enabled
• drilldown node - <DNS name of your OMi node>
• drilldown port - 80 for standard http, 443 if TLS is enabled
• Enable synchronize and transfer control is selected

After you configure the connected server, you can forward events manually from the event browser to the Logfile Adapter. Just select Transfer Control to ... from the Event Browser context menu. You can also configure an automatic forwarding rule using the Event Forwarding manager.

Once an event has been forwarded, you should see a new tab, called External Info, in the Event Details of the for the forwarded event. Selecting this tab calls the sample.LogfileAdapter script getExternalInfo()method to fetch the external information for this event and then display it in the tab. If the call succeeds, the fields on the left will be populated with data.

Make sure you have configured a password for your connected server. This is the password on the last page of the wizard, or the “Incoming Connection” page. You can also find the user name on this page.

Make sure the event you are updating has first been successfully forwarded to the connected server you are authenticating.

• Create your new script under:

  Administration > Setup and Maintenance > Connected Servers

  Click Manage Scripts.

• Configure a new external process connected server and select your script from the drop-down menu.

• Create a forwarding rule with the title “my_forward_test” to forward events automatically to your target connected server.

• Use the sendEvent tool to create a test event:

  <OMi_HOME>/opr/support/sendEvent.bat -t “my_forward_test”

• Check to see if the event was delivered to your server.

Alternatively, you can select Enable Synchronize and Transfer Control in the Connected Server Outgoing Connection screen. You can then manually forward the event from the Event Browser. You can then also check the external event by selecting the External Info tab.

The External Info tab is only for events that have transferred control to an external server. If you forwarded the event using one of the other types of forwarding, for example, Notify, Notify and Update, or Synchronize, then you will not be able to get the external status on the External Info tab. Currently, there is no interface in the Event Browser to view other types of forwarding.

Yes. You can forward an event to as many systems as you like, but you can transfer control to only one system.

This is currently not possible.

Yes. The external system must generate an update using the Event Synchronization Web Service. When the Groovy script method receiveChange()is called, you can set the args property as like this:

args.returnControl

This returns control back to the local OMi instance, assuming the connected server had control and is logged in.

There is a beginners tutorial that you can access here:

http://groovy.codehaus.org/Beginners+Tutorial

Consider this line of code:

def username = args.credentials?.userName

If the value of credentials is null, there will be no attempt at runtime to de-reference it. Null will simply be assigned to username. If the value of credentials is not null, userName will be assigned to username.

A simple way to parse the XML from Groovy is to use the XmlSlurper. See the sample code below and the LogfileAdapter.receiveChange()method.

The following sample assumes a payload with an OPR event (XML). This payload will vary depending upon the connected server sending the update.

  def receiveChange(def args) {
    def timestamp = new Date()
    def externalEvent = args.externalEventChange
    def msg = """### ${timestamp.toString()}: receiveChange() called ###
    parameter externalEvent: ${externalEvent}\n\n"""
    m_logfile.append(msg)
    if ((externalEvent == null) || (externalEvent.length() == 0))
      return false;
    // check if this is an event or event_change
    def xmlNode = new XmlSlurper().parseText(externalEvent);
    if (xmlNode.name().equals("event"))
      return handleEvent(args, xmlNode)
    else if (xmlNode.name().equals("event_change"))
      return handleEventChange(args, xmlNode)
    else {
      def err = "Unexpected object type: ${obj.getClass().canonicalName}"
      m_logfile.append("${err}\n\n")
      m_logger.error(err);
      return false
    }
  }
  def handleEvent(def args, def event) {
    m_logger.debug("Change request received with ${EVENT_TAG} record.")
    // Update the event properties if present in XML
    if (event."title".size())
      args.title = event."title".text()
    if (event."description".size())
      args.description = event."description".text()
    if (event."solution".size())
      args.solution = event."solution".text()
    if (event."severity".size()) {
      def text = event."severity".text()
      def severity = severityMap."${text}"
      if (severity)
        args.severity = severity
      else {
        args.setHttpResponseStatus(400, "Invalid severity: ${text}")
        return false
      }
    }
...

Use a map as follows:

// Map for severity mapping
  static def severityMap = ["0": OprSeverity.unknown,
                            "1": OprSeverity.normal,
                            "2": OprSeverity.warning,
                            "3": OprSeverity.minor,
                            "4": OprSeverity.major,
                            "5": OprSeverity.critical]
...
def externalSeverity = "2"
def oprSeverity = severityMap."${externalSeverity}"

You must implement the following methods in any integration script:

• init()
• destroy()
• forwardEvent()

For more information about script methods, see Groovy script methods.

The following script methods are optional:

• forwardChange(): Only needed if your script adapter supports the following forwarding modes: Notify and Update, Synchronize, or Synchronize and Transfer Control.
• receiveChange(): Only needed if your adapter supports the following forwarding modes: Synchronize or Synchronize and Transfer Control.
• getExternalEvent(): Only needed if your script adapter supports populating the External Info tab in the Event Browser.
• toExternalEvent(): Only needed if your connected server needs to perform a GET HTTP method call at the Event Synchronization Web Service, to retrieve the current properties of the event that originated in OMi.

No. Your script must only implement the required methods. The interface is provided for documentation and for those that wish to use an integrated development environment (IDE) such as Eclipse or IntelliJ.

The init() method gets called when the script is first loaded. There is one instance loaded per connected server and done so on the first access to the connected server. It remains loaded until the connected server configuration is updated, or the script is changed. At that time, the destroy() method is called, and the script is reloaded. Once loaded, the script may maintain state between calls, for example, it may leave connections open to a remote server and reuse those connections on subsequent calls.

For available properties for the init() method, see Properties for init() Method.

Example:

def init(def args) {
    m_logger = args.logger
    m_initArgs = args
    def logfileDir = new File("${args.installDir}${File.separator}${LOG_DIR_REL}")
    if (!logfileDir.exists())
      logfileDir.mkdirs()
    m_logfile = new File(logfileDir, LOGFILE_NAME)
    if (!m_logfile.exists())
      m_logfile.createNewFile()
    m_logger.debug("Logfile Adapter initalized. INSTALL_DIR=${args.installDir}")
    def timestamp = new Date()
    def msg = """### ${timestamp.toString()}: init() called ###
    parameter connected server ID: ${m_initArgs.connectedServerId}
    parameter connected server name: ${m_initArgs.connectedServerName}
    parameter connected server display name: ${m_initArgs.connectedServerDisplayName}
    parameter node: ${m_initArgs.node}
    parameter port: ${m_initArgs.port}
    parameter ssl:  ${m_initArgs.nodeSsl}
    parameter drilldown node: ${m_initArgs.drilldownNode}
    parameter drilldown port: ${m_initArgs.drilldownPort}
    parameter drilldown ssl:  ${m_initArgs.drilldownNodeSsl}\n\n"""
    m_logfile.append(msg)
  }

For details, see the com.hp.opr.api.ws.adapter.InitArgs Javadoc.

For available properties for the ping() method, see Properties for ping() Method.

Example:

def ping(def args) {
    args.outputDetail = "success"
    return true
}

For details, see the com.hp.opr.api.ws.adapter.PingArgs Javadoc.

For available properties for the forwardEvent() method, see Properties for forwardEvent() Method.

Example:

def forwardEvent(def args) {
    def timestamp = new Date()
    def extId = "urn:uuid:${args.event.getId()}"
    def msg = """### ${timestamp.toString()}: forwardEvent() called ###
    event.id: ${args.event.id}
    event.title: ${args.event.title}
    event.state: ${args.event.state}
    event.external.id: ${extId}\n\n"""
    m_logfile.append(msg)
    // Set the external reference ID
    args.externalRefId = extId
    // Make a drilldown to the original event as an example
    args.drilldownUrl =
      new URL("http://${m_initArgs.drilldownNode}:${m_initArgs.drilldownPort}${ROOT_DRILLDOWN_PATH}${args.event.getId()}")
    return true
  }

For more details on the argument passed to the method forwardEvent(), see the com.hp.opr.api.ws.adapter.ForwardEventArgs Javadoc.

For available properties for the forwardChange() method, see Properties for forwardChange() Method.

Example:

def forwardChange(def args) {
    def timestamp = new Date()
    StringBuffer buff = new StringBuffer()
    buff.append("### ${timestamp.toString()}: forwardChange() called ###\n")
    buff.append("    parameter externalRefId: ${args.externalRefId}\n")
    buff.append("    change headline: ${args.changes.headline}\n")
    args.changes.changedProperties.each {
      def propertyChange ->
      buff.append("    changed property: ${propertyChange.propertyName}=${propertyChange.currentValue}\n")
    }
    buff.append("\n")
    m_logfile.append(buff.toString())
    return true
  }

For more details on the argument passed to the method forwardChange(), see the com.hp.opr.api.ws.adapter.ForwardChangeArgs Javadoc.

For available properties for the receiveChange() method, see Properties for receiveChange() Method.

Example:

def receiveChange(def args) {
    def timestamp = new Date()
    def msg = """### ${timestamp.toString()}: receiveChange() called ###
    parameter externalEvent: ${args.getExternalEventChange()}\n\n"""
    m_logfile.append(msg)
    def jc = javax.xml.bind.JAXBContext.JAXBContext.newInstance(
com.hp.opr.api.ws.model.event.OprEvent.class)
    def event = jc.createUnmarshaller().unmarshal(
new CharArrayReader(args.externalEventChange.toCharArray()))
    if (event instanceof com.hp.opr.api.ws.model.event.OprEvent) {
      if (event.titleUpdated)
        args.title = event.title
      if (event.descriptionUpdated)
        args.description = event.description
      if (event.solutionUpdated)
        args.solution = event.solution
      return true
    } else {
      def err = "Unexpected object type: ${obj.getClass().canonicalName}"
      m_logfile.append("${err}\n\n")
      m_logger.error(err);
      return false
    }
  }

For more details on the argument passed to the method receiveChange(), see the com.hp.opr.api.ws.adapter.ReceiveChangeArgs Javadoc.

The args has a method to allow you to control the response:

args.setHttpResponseStatus(400, "My response message")

You can set the HTTP status and payload to anything you wish. If the value is less than 300, the payload is processed after the receiveChange() method is called. Then the status and message are returned to the web service caller, otherwise the HTTP status and message are returned immediately to the we service caller.

For available properties for the getExternalEvent() method, see Properties for getExternalEvent() Method.

Example:

def getExternalEvent(def args) {
    def timestamp = new Date()
    def msg = """### ${timestamp.toString()}: getExternalEvent() called ###\n\n"""
    m_logfile.append(msg)
    args.assignedUser = "logger"
    args.assignedGroup = "logging group"
    args.state = "open"
    args.severity = "normal"
    args.priority = "none"
    return true
  }

For more details on the argument passed to the method getExternalEvent() see the com.hp.opr.api.ws.adapter.GetExternalEventArgs Javadoc.

All properties available in the Event Browser, or that can be found in the Event Web Service are available in the OprEvent object. Details can be found in the Javadoc for OprEvent.

For an example go to the Event Web Service and list the events:

https://<server.example.com>/opr-web/rest/9.10/event_list

The XML output will give you a good idea of the properties that are available. This XML output is directly generated from the OprEvent object.

event.relatedCi returns an object with properties describing the related CI. It is of type OprRelatedCi. event.relatedCi.configurationItem contains the key properties of the CI, and, if the CI is part of another CI, it contains the CI it is part of: event.relatedCi.configurationItem.partOf. "partOf" is of type OprRelatedCi, so this will continue until there are no more parts. This should provide you with enough details to identify the CI in an external system.

Use the OprConfigurationItem utility method to get the other properties: getProperty(name), or for a map of all properties call getProperties().

Call the utility method getCi(id) for the CI you want. All properties will be set in the CI that is returned from this method. This utility method is available in the args for forwardEvent(), forwardChange(), and receiveChanges().

The possible class types are:

• String
• Boolean
• Integer
• Long
• Float
• Double
• Date

If the CI property is a list, you will get multiple entries.

Check the following:

• Make sure the connected server is "Active". Found on "General" tab.
• Make sure the connected server supports "Ownership Transfer". Found on "Outgoing Connection" tab.

Try the following:

• Switch logging to debug level.
• Check the log file.

You can view the log file at this location:

<OMi_HOME>/log/<process>/opr-event-sync-adapter.log

where <process> is jboss/wde/opr-scripting-host.

For getExternalEvent() method calls, you must edit the following properties file:

<OMi_HOME>/conf/core/Tools/log4j/jboss/opr-event-sync-adapter.properties

For all other method calls, edit the following properties files:

<OMi_HOME>/conf/core/Tools/log4j/wde/opr-event-sync-adapter.properties

<OMi_HOME>/conf/core/Tools/log4j/opr-scripting-host/opr-scripting-host.properties

You need to set the loglevel parameter towards the top of the file. The file contains possible values.

The args passed to the init() method has a property called logger. Use this logger for logging. For example:

def logger = args.logger
logger.info("This is an info log")
logger.warn("This is a warning log")
logger.error("This is a error log")
logger.debug("This is a debug log")
logger.error("This is a error log with an exception", exception)