Incident Exchange between Operations Manager i and Service Management Automation

BSM enables you to forward events from Operations Manager i (OMi) to Service Management Automation (SMA) and update the OMi events based on Service Management incidents.

You can also drill down from OMi events to Service Management incidents and vice versa.

Before configuring the integration, complete the following procedures to upload the CA certificate to OMi’s global trust store.

1. If you have replaced the certificates for the suite with CA trusted certificates, copy the certificate to:

   • (Windows only) C:\HPBSM\bin
   • (Linux only) opt/HP/BSM/bin

2. On the system running OMi,

   • (Windows only) Open a command prompt and run the following command to import the certificate:

     C:\HPBSM\bin>opr-cert-mgmt.bat -import <alais name> <certificate name>.ce

     Restart OMi.

   • (Linux only) Run the following command to import the certificate:

     # ./opr-cert-mgmt.sh -import <alais name> <certificate name>.cer

     Go to cd /opt/HP/BSM/scripts and run the following command to restart OMi.

     # ./run_hpbsm restart

Step 1: Configure Service Management Automation to communicate with OMi

Configuring Service Management Automation to communicate with OMi requires configuring an agent, endpoint, and External system record, and installing and configuring the On Premise Bridge agent. These records, along with the On Premise Bridge, are used by Service Management Automation to synchronize events back to OMi. The External system record is used in conjunction with a user account for authorizing case exchange requests from external systems. It is best to create a user account for this integration. Do not use the account of a real user that will log in via the browser and update tickets through the Service Management user interface. Updates made by the authorized user of an external system do not trigger case exchange update requests back to original external system.

To configure a Service Management agent, complete the following steps in the Service Management:

1. From the Administration menu of the Service Management user interface, navigate to: Integration > Agents.
2. Click Add to add a new agent.
3. Specify the name for this agent. In this example, we will use OMi_Agent.
4. Enter a description (optional) and click Download connection file.
5. Save the downloaded server-connection.conf file for later use.

Download, install, and configure the On-Premise Bridge agent on a local server:

1. From the Service Management Agents page, click Download agent in the top right corner of the page.
2. Install the downloaded On-Premise Bridge agent on a local windows server. The agent will act as a forwarding agent to send Service Management incident updates back to OMi. Follow the on-screen prompts and enter appropriate credential and proxy information for Service Management. For more information, refer to On-Premise Bridge Agents and Endpoints.
3. Copy the server-connection.conf file downloaded from the agent configuration steps to: <Agent_installation_directory>/product/conf.
4. Launch the Endpoint Credentials Manager for the On Premise Bridge agent. The shortcut is located in the Start menu under MicroFocus > On-Premise Bridge Agent.
5. Click New.
6. Enter a name for this credential. In this example we will use OMi_Credentials.
7. Enter user and password information (repeat the password in the Confirm password field). These will be used as OMi credentials for sending incident updates to OMi. In this example we will set the user to Service Management 1. The user name will be used later during the OMi Connected Server setup step and it will correspond to the Name property of the connected server.
8. Click Save and close the Endpoint Credentials Manager.
9. Stop the On-Premise Bridge agent and restart it.

For more information on installing the On Premise Bridge agent, refer to SMAX help center.

To configure a Service Management endpoint, perform the following steps in Service Management:

1. From the Administration menu of the Service Management user interface, navigate to: Integration > Endpoints or if you are still on the Agents page, click the Endpoints submenu link.
2. Click Add to add a new endpoint.
3. For the Endpoint type field, select Rest Executor 1.0.
4. For the Endpoint name, enter a name for this endpoint. For this example we will use OMi_Endpoint.
5. For the Running on agent field, select the agent created earlier. In this example, we used OMi_Agent.
6. Click Add.
7. Click Configure.
8. Enter the location of the OMi Server. This should be in the form http:// followed by the fully qualified domain name followed by /opr-gateway/. In this example, we will use http://omihost.domain.com/opr-gateway/.

9. In the Credentials field, select the credential name entered in the On Premise Bridge Endpoint Credentials Manager. In this example we used OMi_Credentials.

   Note It may take a few seconds for the credentials to appear in the drop-down selection list. If the credentials do not appear, review the steps for configuring the On Premise Bridge agent. You may also review the log output located at <Agent_installation_directory>/product/log/controller/controller.log.

10. Click Save.

To configure the Service Management external system record, complete the following steps in Service Management:

1. From the Administration menu of the Service Management user interface, navigate to: Integration > External Systems.
2. Click New to add a new External System.

3. Enter a system ID. This will be the identifier of the OMi External System. In this example we will use OMi.

4. Enter a description. For this example we will use Operations Management i.

5. Select an authorized user. As stated before, this should be a integration user account. For this example we will use sample-integration-user@sampledomain.com.

6. Click Edit and expand the Outgoing Exchange Operations section.

7. In the Endpoint field, select the endpoint created earlier. In this example we will use OMi_Endpoint.

8. Click Apply Configuration.

9. In the popup, for the External configuration field, select the OMI 9.2X entry that is available out-of-the-box and click Confirm.

10. Click Save.

Step 2: Configure a Service Management Groovy Script adapter

To properly integrate with your Service Management instance, OMi communicates by sending and receiving Json-based REST messages to and from Service Management. To configure the Groovy script adapter, you must set the Tenant Id and the configured External System record System ID from Service Management in the Groovy script.

To configure a Service Management Groovy adapter, perform the following steps:

1. Download the SMAGroovyAdapter script from Marketplace. Select the correct adapter for your version of OMi (9.2x or 10.0).
2. If you are working in OMi 9.2x, download the following two jar files from sourceforge.net: ezmorph-1.0.2.jar and json-lib-2.4-jdk15.jar.
3. In OMi, navigate to the Connected Servers configuration screen: Admin > Operations Management > Setup (tab) > Connected Servers.
4. Click the Manage Scripts icon.
5. Click New (*) to create a new script.
6. Enter the Display Name of: sa:SMAAdapter and click Next.
7. Replace the default script with the contents of the downloaded SMAGroovyAdapter.

8. Edit the following integration settings (located just after the import statements from the top):

   • SMA_TENANTID. Set to the Tenant ID of your Service Management tenant. It is located at the bottom right corner of the Main Menu in Service Management.
   • EXTERNAL_SYSTEM_ID. Set to the System ID defined in the External System Record created from Step 1: Configure Service Management Automation to communicate with OMi.

   Note If necessary, the communication between Service Management and OMi can be done via a proxy server. For details, see the comments in the groovy script describing the proxy configuration for PROXY_HOST & PROXY_PORT.

9. Click Next. The class path appears on the screen.
10. If you are working in OMi 9.2x, add the two jar files downloaded to the class path with the ezmorph jar file positioned above the json-lib jar file.
11. Set the Timeout to 6000 ms and click Finish.

Step 3: Configure Service Management as an OMi connected server

Synchronizing events and event changes in OMi with Service Management incidents requires configuring a connected server within OMi to correctly identify the target Service Management instance. To achieve this, configure Service Management as a target connected server in the Connected Servers manager. For full details about how to configure a connected server, see the Connecting Servers section of the OMi online help.

To configure Service Management as a target connected server, perform the following steps:

1. Navigate to the Connected Servers manager in the OMi user interface: Admin > Operations Management > Setup > Connected Servers
2. Click the New ( * ) button to open the Create New Server Connection dialog box.

3. In the Display Name field, enter the desired name for Service Management. By default, the Name field is filled automatically. For example, if you enter SMA1 as the Display Name for Service Management, SMA_1 is automatically inserted in the Name field. You can specify a custom name in the Name field, in place of the default name.

   Optional: Enter a description for the new target server.

   Make sure that you check the Active check box. Click Next.

4. Select External Event Processing to choose the server type suitable for an external incident manager like Service Management. Click Next.
5. Enter the Fully Qualified DNS Name for Service Management. Click Next.

6. From the Integration Type dialog box:

   1. Select Call Script Adapter as the integration type.
   2. From the Script Name menu, select the Service Management Groovy script adapter configured in Step 2: Configure a Service Management Groovy Script adapter.
   3. Click Next.

7. In the OMi user interface, in the Outgoing Connection dialog box, enter the account credentials specified in the External System record Authorized User property:

   1. In the User Name field, enter the user name for the Integration User you set up in Service Management.
   2. In the Password field, enter the password for the user you just specified. Repeat the password entry in the Password (Repeat) field.

   3. In the Port field, specify the secure port for Service Management. The default SSL port is 443. Make sure that the Use secure HTTP check box is selected.

   4. Select Enable Synchronize and Transfer Control.

      If Enable Synchronize and Transfer Control is selected, an OMi operator can transfer ownership of the event to the target connected server using the Transfer Control option in the Event Browser context menu.

      If it is not selected, the Synchronize and Transfer Control option is not available from the Event Browser context menu or from the list of forwarding types for configuring forwarding rules.

   5. Test the connection. A Success or ERROR hyperlink is displayed. Click the link to get a more detailed message.

      See the following examples:

      • Error: Ping failed due to the following error: Request to Connected Server 'Sample Name' on node 'sample.hostname' failed with exception: java.net.UnknownHostException.

        Solution: Check to ensure that the hostname for the Service Management server is correct.

      • Error: Ping failed due to the following error: HTTP request to Connected Server Sample Name' on node 'sample.hostname' failed with HTTP status: (500) Internal Server Error.

        Solution: Check to ensure that the Groovy Adapter properties for SMA_TENANTID and EXTERNAL_SYSTEM_ID and the username and password are correct. Also check to ensure that all of these settings correspond to the External System record settings within Service Management.

   6. Click Next.

8. If you want the additional ability to drill down into Service Management from the generated incidents, you must specify the fully qualified DNS name and port of Service Management. Click Next.

Step 4: Configure an event forwarding rule

The next step is to configure an event forwarding rule that determines which events are forwarded automatically to Service Management. Refer to the OMi online help for full details about configuring filters.

To configure a forwarding rule, perform the following steps:

1. Navigate to the Forwarding Rules manager in the OMi user interface: Admin > Operations Management > Event Automation > Event Forwarding.
2. Click the New item button to open the Create New Forwarding Rule dialog box.

3. In the Display Name field, enter a name for the forwarding rule, in this example Forward Critical (Sync and Transfer Control).

   Optional: Enter a description for the forwarding rule you are creating.

   Make sure the Activate Rule after creation check box is selected. A rule must be active for its status to be available in Service Management.

4. Click the Browse button next to the Event Filter field. The Select an Event Filter dialog box opens. In the Select an Event Filter dialog box, do one of the following:

   • Select an existing filter

   • Create a new filter as follows:

     1. Click the New button to open the Filter Configuration dialog box.
     2. In the Filter Display Name field, enter a name for the new filter, in this example, FilterCritical. Clear the check boxes for all severity levels except for the Critical severity. Click OK.
     3. You should see your new filter in the Select an Event Filter dialog box (select it, if it is not already highlighted). Click OK.

5. Under Target Servers, select the target connected server you configured in the section Step 3: Configure Service Management as an OMi connected server. In this example, this is SMA1.

   Click the Add target server button next to the target servers selection field. You can now see the connected server’s details. In the Forwarding Type field, select the Synchronize and Transfer Control forwarding type. Click OK.

   For more information on configuring an Event Forwarding Rule, refer to the Operations Management Help.

   Note It is important to minimize a system overload resulting from the creation of multiple incidents in Service Management. It is recommended to use advanced filters such that events generated from failures to communicate with Service Management do not attempt to generate incidents for Service Management.

Step 5: Test the connection

To test the connection, send an event to the server hosting OMi that matches the filter you defined (in our example filter, the severity value is Critical), and then verify that the event is forwarded to Service Management as expected.

To test the connection, do the following:

1. On the Gateway Server system running OMi, open an Event Browser.
2. On the system running OMi, open a command prompt and change to the following directory: <HPBSM root directory>\opr\support.
3. Send an event using the following command: sendevent -s critical -t test111-1.
4. Verify that the event appears in the OMi Event Browser.
5. Select the Forwarding tab.
6. In the External Id field, you should see a valid Service Management incident ID.

7. Verify that the incident appears in the Incident Details in Service Management:

   If the event drill-down connection is configured correctly, you can click the hyperlink created with the Incident ID. A browser window opens, which takes you directly to the incident in the Incident details in Service Management, if you are already logged in. If you are not logged in, you are taken to the Service Management login page.

   If the event drill-down connection is not configured, do the following:

   1. In the Forwarding tab in the OMi Event Browser, copy the incident ID from the External Id field.
   2. In the Service Management user interface, click the global search icon at the top right of the web browser:
   3. Paste the incident ID into the search field.
   4. Click the Search button.
   5. Click the Incident ID from the search results. This takes you to the incident in the Incident Details.

Step 6: Synchronize attributes

Not all attributes are synchronized to Service Management from OMi by default in every instance. When the Service Management incident is initially created from an OMi event, all required properties for incident creation in Service Management are populated with values from the event attributes, and the remainder are populated from default values as configured in the Service Management Groovy adapter. After the initial incident creation, whenever the incident or event subsequently changes, only some of the event and incident attributes are synchronized. The following describes how to customize the list of attributes to synchronize upon changes.

OMi to Service Managementrequired attributes for incident creation.

The following attributes must be transferred from OMi to Service Management at the time of initial event creation. The transfer of control of the event is configured in the Connected Servers manager.

Most of these attributes have default values which can be set in the Groovy script adapter for Service Management:

• Title
• Description
• Severity
• Category
• Assigned Group
• Most Critically Affected Business Service

Priority is a calculated value in Service Management based on Urgency and Impact. An event's severity is mapped to an incident's Urgency, and since there is no Impact attribute for events, a default value for Impact is specified in the Service Management

Attribute synchronization using Groovy scripts

If you want to change the out-of-the-box behavior regarding the attributes that are updated, you must specify the attributes in a Groovy script.You should specify:

• the fields that are updated in Service Management
• the fields that are posted to Service Management as comments
• the fields that are updated in the OMi event from Service Management
• the custom properties from Service Management and OMi.

You can also specify custom attributes in the Groovy script.

Tips for customizing Groovy scripts

This section provides some tips about customizing Groovy scripts. Below we provide a few examples of what can be customized. Look at the configuration section of a Groovy script to see further items that can be modified. In the configuration section of a Groovy script, you can define and modify the attributes that are to be synchronized between OMi and Service Management. The configuration section of a Groovy script also contains the default value mappings for the following fields:

• Category
• Completion code
• Description
• Impact scope
• Service
• Service desk group
• Urgency

You can also modify these default values, as well as the mappings for enumerated properties. More advanced configuration can be done in other parts of the Groovy script, if necessary.

The beginning and the end of the configuration section of a Groovy script is marked as follows:

Controlling attribute synchronization

You can control how updates to attributes are synchronized from OMi to Service Management by setting variables in the Groovy script. Variables with the word Comments in the name define the properties that are posted to Service Management as comments.

Use the following properties to define the properties that are synchronized on a Create Incident action:

• private static final Set SyncOPRPropertiesToSMAOnCreate = ["initiated_by", "category", "assigned_group", "drill_down_url"]
• private static final Set SyncOPRPropertiesToSMACommentsOnCreate = ["initiated_by", "time_created", "time_received","related_ci"]

Use the following properties to define the properties that are always synchronized:

• private static final Set SyncOPRPropertiesToSMA = ["title", "description", "state", "severity", "solution", "cause"]
• private static final Set SyncOPRPropertiesToSMAComments = ["title", "description", "state", "time_state_changed", "severity", "priority", "annotation", "duplicate_count", "cause", "symptoms", "assigned_user", "assigned_group", "control_transferred_to"]

Edit the following variable to define the properties that are synchronized to OMi event properties:

• private static final Set SyncSMAPropertiesToOPR = ["DisplayLabel", "Description", "PhaseId", "Solution"]

Edit the following variables to control which enumerated values in the corresponding OMi Event State, Severity, and Priority fields to synchronize with the Service Management Incident PhaseId, Urgency and Priorities fields:

• private static final Set SyncOPRStatesToSMA = ["closed"]
• private static final Set SyncOPRSeveritiesToSMA = ["*"]
• private static final Set SyncOPRPrioritiesToSMA = ["*"]
• private static final Set SyncSMAPhasesToOPR = ["Validate", "Close"]
• private static final Set SyncSMAUrgenciesToOPR = ["*"]
• private static final Set SyncSMAPrioritiesToOPR = ["*"]

Edit the following variables to define the custom attributes to synchronize between OMi and Service Management:

• private static final Map<String, String> MapOPR2SMACustomAttribute = [:]
• private static final Map<String, String> MapSMA2OPRCustomAttribute = [:]

For example: private static final Map<String, String> MapOPR2SMACustomAttribute = ["CustomOMiEventAttribute":"CustomSMAAttribute_c"]

Edit the following map variables to control the mapping of the corresponding enumeration values between the OMi Event and Service Management Incidents:

• private static final Map MapOPRState2SMAPhase = ["open": "Classify", "in_progress": "InitialSupport", "resolved": "Validate", "closed": "Close"]
• private static final Map MapSMAPhase2OPRState = ["Log": "open", "Classify": "open", "InitialSupport": "in_progress", "Escalate": "in_progress", "Validate": "resolved", "Close": "closed"]
• private static final Map MapOPRSeverity2SMAUrgency = ["critical": "TotalLossOfService", "major": "SevereDisruption", "minor": "SlightDisruption", "warning":"NoDisruption", "normal": "NoDisruption", "unknown": "NoDisruption"]
• private static final Map MapSMAUrgency2OPRSeverity = ["TotalLossOfService":"critical", "SevereDisruption":"major", "SlightDisruption":"minor", "NoDisruption":"normal"]
• private static final Map MapOPR2SMAPriority = ["highest": "CriticalPriority", "high": "HighPriority", "medium": "MediumPriority", "low": "LowPriority", "lowest": "4", "none": "4"]
• private static final Map MapSMA2OPRPriority = ["CriticalPriority": "highest", "HighPriority": "high", "MediumPriority": "medium", "LowPriority": "low"]

The following configurable properties can be synchronized to Service Management incident properties:

• drill_down_url
• title
• description
• severity
• solution
• state
• category
• assigned_user
• assigned_group
• initiated_by
• cause
• symptom

The following configurable properties can be synchronized to Service Management comments:

• Id
• title
• description
• state
• priority
• severity
• service
• category
• subcategory
• application
• object
• original_data
• assigned_group
• assigned_user
• time_created
• time_received
• time_state_changed
• solution
• initiated_by
• related_ci
• control_transferred_to
• cause
• symptoms
• duplicate_count

The following configurable properties can be synchronized to OMi Events:

• DisplayLabel
• Description
• Urgency
• Priority
• PhaseId
• Solution

Edit the Service Management External System record, outgoing exchange operation payloads.

The payloads for each of the outgoing exchange operations may be edited to add additional properties to synchronize back to OMi Events. In addition, the payload must evaluate to a valid json structure. You can copy the payload and use external tools to validate the structure evaluates to a valid json structure. The url suffix and payloads of Service Management use DSL parsing to be constructed. The following two variables can be used to reference property values from the corresponding records in Service Management:

• ${:entity} represents the Incident
• ${:current_update_association} represent to the External Reference record

Example: ${:entity.DisplayLabel} represents the value of the Incident title.

Check the OMi <HPBSM root directory>/log/opr-scripting-host/opr-event-sync-adapter.log for errors related to parsing the Service Management update payloads.

Set the log4j debug level in <HPBSM root directory>/conf/core/Tools/log4j/opr-scripting-host/opr-event-sync-adapter.properties to get additional debug and error messages in the opr-event-sync-adapter.log.

Mapping OPR lifecycle states to Service Management phases

Individual OPR event state and Service Management incident phase changes may be selected for synchronization. By default, only the closed state is synchronized. To change this behavior, add the desired states to the SyncOPRStatesToSMA list.

See the following example:

In the example the OPR event lifecycle states closed, in_progress, and resolved are synchronized to the Service Management incident phases.

Additionally, maps are used to specify the mapping of OPR event attributes to Service Management incident fields. The maps are named MapOPRState2SMAPhase, MapOPRSeverity2SMAUrgency, and MapOPR2SMAPriority. Out of the box, all possible values have a mapping.

See the following example:

Syntax errors

If you get a syntax error when customizing your Groovy scripts, an event is generated in the Event Browser with a detailed description of the error. In addition you may view the log file opr-eventsync-adapter.log for information about how to resolve the error. The log file is located here:

<Gateway Server root directory>/log/opr-event-sync-adapter.log