EPI script for event enrichment

One of the requirements with regards to accessing the RTSM via the JAVA API is that a connection needs to be established first, including providing credentials for a valid user. Establishing the connection involves processing overhead and it is not practical to open and close a new connection for each event being processed. For EPI scripts, you must minimize the processing time for each event being handled.

To minimize processing time, you can pre-load a simple script-internal HashMap containing CI ObjectIDs linked to a string containing the corresponding value of the CI attribute used for creating our event CA. The pre-loaded HashMap resides in memory, and enables fast retrieval of a small subset of RTSM information.

The init() method is used to establish a connection to the RTSM. A separate thread is started in which the HashMap is initialized. This thread is also synchronized with the main thread (via a synchronization object) so that the HashMap can be momentarily blocked and reloaded after a specified wait period (for example 10 minutes).

The process() method is used to:

• Retrieve the ObjectID of the event’s related CI

• Access the HashMap to obtain the “owner” information

• Invoke event.AddCustomAttribute to create the CA

The destroy() method (called when the script is unloaded or de-activated) is used to release the memory used by the HashMap.

To retrieve a set of CIs from the RTSM, a TQL query is executed using the HPE UCMDB API. For full documentation on the available APIs, see HPE UCMDB API Reference. These files are located in the following folder:

<OMi_HOME_GW>/AppServer/webapps/site.war/amdocs/eng/API_docs/UCMDB_JavaAPl

The script illustrates how to execute a “named query" (a query that has already been defined in the RTSM).

After CIs are retrieved via the query, the HashMap must be initialized. For each CI in the query result, the ObjectID and the corresponding string value of the attribute (obtained via the ci.getPropertyValue method) are loaded. Any string attribute can be used.

The background thread loads a parallel map (newMap) in the part of the code that is not synchronized with the main thread. When the thread gets the lock (is synchronized), it initializes the “run-time” HashMap (ownerMap) from the temporary one. This is a safe and effective approach to keeping the HashMap up to date to reflect ongoing changes in the RTSM topology

To enrich events during event processing after the CI has been resolved with CI attributes from the RTSM, the following definition can be used in your EPI Groovy scripts:

def ucmdbServiceProvider
UcmdbService ucmdbServiceAccess = null

The following OwnerResolver script template illustrates how the definition can be used:

import com.hp.ucmdb.api.UcmdbService
import com.hp.ucmdb.api.UcmdbServiceProvider
import com.hp.ucmdb.api.topology.Topology
import com.hp.ucmdb.api.topology.TopologyQueryService
import com.hp.ucmdb.api.types.TopologyCI
import org.apache.commons.logging.Log
import org.apache.commons.logging.LogFactory

class OwnerResolver {
  private static Log s_log = LogFactory.getLog(OwnerResolver.class.canonicalName)

  final String QUERY_NAME = "OMiOwnerRes"

  HashMap<String, String> ownerMap = new HashMap<String, String>()
  boolean running = true
  UcmdbServiceProvider provider
  UcmdbService ucmdbServiceAccess = null
  final Object syncObject = new Object()

  void init() {

    ucmdbServiceAccess = ucmdbService.getCmdbService()

    Thread.start {
      while (running) {
        TopologyQueryService tqs = ucmdbServiceAccess.getTopologyQueryService()
        Topology topology = tqs.executeNamedQuery(QUERY_NAME)
        HashMap<String, String> newMap = new HashMap<String, String>()
        topology.getAllCIs().each { TopologyCI ci ->
          final String ciId = ci.id.getAsString()
          final String owner = ci.getPropertyValue("discovered_contact")
          if (owner)
            newMap.put(ciId, owner)
          s_log.debug("CI with ID=${ciId} owned by ${owner}")
        }
        synchronized (syncObject) {
          ownerMap = newMap
          s_log.info("Owner map initialized with " + ownerMap.size() + " entries.")
          try {
            syncObject.wait(600000)
          }
          catch (InterruptedException ignore) {
            // ignore
          }
        }
      }
    }
  }

  void destroy() {
    ownerMap = null
    running = false
    synchronized (syncObject) {
      syncObject.notifyAll()
    }
  }

  void process(eventList) {
    synchronized (syncObject) {
      eventList.each { event ->
        def ciId = event.getRelatedCiId()
        if (!ciId) // Check for empty CI Id
          s_log.warn("Related CI ID is NULL or empty")
        else {
          s_log.info("Related CI ID = " + ciId)
          String owner = ownerMap.get(ciId)
          if (owner) {
            s_log.info("CI Owner = " + owner)
            event.addCustomAttribute('CONTACT', owner)
          } else {
            s_log.info("Owner not found for CI with id=" + ciId + ". Owner 
            map has " + ownerMap.size() + " entries.")
          }
        }
      }
    }
  }

}

Some tips for using scripts for retrieving RTSM data:

• Use conditions in your query to limit the CIs returned to only those that have some value in the attribute you want to use. This avoids loading CIs with no corresponding attribute value.

• Be mindful of how many CIs the query returns. Do a Calculate Query Result Count in RTSM Administration before using the query within the script. The more CIs it returns, the more memory will be required for the HashMap.

• The script name must be the same as the class name specified in the script. The script name is saved under:

  Administration > Event Processing > Automation > Event Processing Customizations

  Alternatively, click Event Processing Customizations.

• Use the actual CI attribute name in the script, NOT the display name (in the getPropertyValue method)

• You can find the time taken by your script for each event from the following log file:

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

The following procedure describes how to use a script to enrich events during event processing after the CI has been resolved with CI attributes from the RTSM:

1. Define a TQL query in the Modeling Studio that returns the CIs of interest:

   Administration > RTSM Administration > Modeling > Modeling Studio

   Alternatively, click Modeling Studio.

   

   In this example, the OMiOwnerRes query returns CIs of type Node that have a value of NOT null for the attribute DiscoveredContact.

   Note DiscoveredContact is a standard attribute of the Node CIs type. You need to manually add values to the DiscoveredContact attribute for each node CI so that the example returns contact names in the Contact column of the Event Browser.

   The Node CI Type conditions are set in the Query Node Properties dialog box as follows:

   

2. To make the DiscoveredContact attribute available to the RTSM JAVA API, you must mark it for calculation under “Element Layout”:

   

3. Install the script (in this case, with appropriate hostname, credentials, query name, and CI attribute name specified) in the After CI/ETI Resolution pipeline step.

   Note No special classpath is required.

4. Exposed the CONTACT CA for use in your browser by configuring the CA in the Available Custom Attributes Operations Management Infrastructure Settings:

   1. Open Infrastructure Settings:

      Administration > Setup and Maintenance > Infrastructure Settings

      Alternatively, click Infrastructure Settings.

   2. Select Applications and use the list to set the administration context to Operations Management.

   3. Open the Available Custom Attributes item in the Custom Attributes Setting pane.

   4. Add CONTACT as a new value.

   

5. Modify your browser columns to show the new CA (CONTACT).

   

   The DiscoveredContact attribute from the RTSM is used to populate the CONTACT column.

   Some fields in the CONTACT column are empty because the related CI Type is not Node (or child CI Type of Node). As a result, there is nothing in the HashMap because this CI Type is not included in the TQL used to build the HashMap.