HP BSM Operations Manager i (OMi)
With the xMatters and HP OMi integration, the appropriate technician can be notified directly via voice, email, push notification or pager. Information about the failure is presented to the recipient so decisions can be made in real-time.
Once a response is submitted using the recipient’s device, xMatterswill update the HP OMi event in real-time. The benefit is that this process is immediate – significantly faster than the time required for staff to notice the failures or malfunctions, determine who is on call, and manually notify the right person. In addition, the ability to take simple actions on the event from any device gives the event resolver a quick way to deal with many issues and communicate to other team members the current state of the event.
During the process, every notification, response, and action is logged in xMatters. In addition, xMattersautomatically annotates the original event with status information.
The xMattersproduct features a self-service web user interface to allow accurate assignment of responsible personnel for each job. xMatters also includes a Subscription panel that allows both managed and self-subscription to HP OMi events.
This integration does not support the Bulk Transfer feature in HP OMi; each event must be sent to the Integration Agentseparately. Attempting to use bulk transfer or similar options may result in the Integration Agent receiving only a partial message, and will cause the integration to time out.
The instructions cover the following topics:
- Before you begin: download the workflow
- Configure xMatters: create an integration user and a web service user, import the workflow,
- Configure the Integration Agent: install and configure the integration files, set the password files, and enable deduplication
- Configure HP OMi: Create a connected server, create an event forwarding rule
- How to use the integration: trigger a notification, respond to it, and view the results
- Download resources: where to download the workflow
Download the workflow
The .zip file contains all of the components required by xMatters and HP OMi. Download the workflow .zip file to a location on your local machine, and extract the contents.
You may also notice that there is another .zip file within the extracted integration archive. This is the workflow itself, which contains pre-configured forms, properties, and messages specifically designed for HP OMi. Do NOT extract the contents of the workflow .zip file! You'll be able to import it directly into xMatters.
The first step in configuring this integration is to set up the components on the xMatters side:
- Set up an integration user that HP OMi will use to authenticate with xMatters.
- Create a web service user for the Integration Agent.
- Import the workflow.
- Gather the URLs and IDs you need to complete the configuration in HP OMi and the Integration Agent.
This integration requires a user who can authenticate REST web service calls when working with events. These permissions are provided by the "REST Web Service User" role in xMatters. See Create an integration user for more information.
Keep the user ID and password of this user handy — you'll need them when configuring other parts of this integration.
This integration requires a web service user with specific permissions in xMatters to receive user responses and notifications about event status changes for the Integration Agent.
"Web service users" are a specific type of user in xMattersthat can work with the SOAP web services used by the Integration Agent; this means you can't just use a regular user and assign them a specific role or permission, you have to create a dedicated user.
- In xMatters, click the Users tab, and select Add Web Service User .
- On the Add Web Service User page, enter a User ID and Password for the new web service user.
- In the Denied Web Services list, locate and select the following web services, and then click Add:
- Query User
- Receive APXML
- Register Integration Agent
- Submit APXML
- Click Save.
The next step is to import the workflow. You can find the workflow .zip file in the extracted archive you downloaded.
- In xMatters, click the Workflows tab, and then click Import.
- Browse to the .zip file you downloaded, or drag it onto the Import Workflow dialog box.
- Click Import Workflow.
- Once the import is finished, the workflow should be automatically enabled. If it isn't, click the Disabled toggle to enable it.
- Click the gear icon beside the workflow, and select Editor Permissions.
- Add the integration user, and then click Save.
- Click the workflow name to open the Forms tab.
- For the first form in the list (Spectrum Incidents), click the Web Service drop-down, and then select Sender Permissions.
- Add the integration user, and then click Save Changes.
- Repeat steps 7-8 for each of the other forms.
Some configuration fields require a UUID (Universal Unique Identifier) for a specific component or property in a workflow — usually the responses. To retrieve the identifier for an element, look for the API icon in the xMatters user interface:
Clicking this button displays the identifier for the component in a dialog box; you can copy and paste the string to the appropriate location in the Integration Agent configuration file.
As an example, the following instructions describe how to retrieve the UUID for a specific response choice; the process is similar for any identifier you want to determine.
To retrieve the identifier for a response choice:
- In xMatters, open the HP OMi workflow.
- On the Spectrum Incidents form, click Edit > Responses.
- Beside the Acknowledged response, click the API icon.
Now that you've configured xMatters, it's time to configure the Integration Agent. This involves installing and configuring the integration files, setting up the password files, and enabling deduplication to suppress duplicate events.
To configure the Integration Agent for the HP OMi integration, you must copy the integration components into the Integration Agent; this process is similar to patching the application, where instead of copying files and folders one by one,you copy the contents of a single folder directly into the Integration Agent folder (<IAHOME>). The folder structure is identical to the existing Integration Agentinstallation, so copying the folder's contents automatically installs the required files to their appropriate locations. Copying these files will not overwrite any existing integrations. If you have more than one Integration Agentproviding the "hpomi-3-0" service, repeat the following steps for each one. If you are not certain of the settings required in this section, consult your HP OMi administrator
The installation instructions below assume you already have a working xMatters Integration Agent If this is a new installation and you have not yet deployed the Integration Agent, download, deploy, and configure the Integration Agent before continuing.
The following instructions use <IAHOME> to refer to the installation folder of the Integration Agenton your system. Change this to the path on your system as needed. If you have already installed an existing integration, ensure that you backup the deduplicator-filter.xml file (if one exists) in the <IAHOME>\conf folder before you install this integration.
The installation package contains all that you need to configure the integration.
- Within the extracted integration archive, navigate to components/integration-agent/integrationservices, and copy the entire contents of the folder to the <IAHOME>/integrationservices directory.
- Open the <IAHOME>/conf/IAConfig.xml file and add the following line to the "service-configs" section:
- Save and close the file.
- Open the <IAHOME>/integrationservices/hpomi-3-0/configuration.js file and add or set the values for the following variables:
|OMI_SERVER||To configure this setting, replace the default value of "localhost" with the fully qualified DNS name of the HP OMi Gateway server. The default value is: localhost|
|OMI_PROTOCOL||The protocol used for HP OMi connectivity; the default value is "http". To enable SSL communication, replace the default value with "https".|
|OMI_PORT||To configure this setting, replace the default value of "80" with the port number of your HP OMi server.|
|OMI_USER||Specifies the username of the web services client account to use when connecting to the HP OMi web services; the default value is "xMatters". Note that this user name is case-sensitive, and must match the name of the defined connected server.|
|OMI_PASSWORE_FILE||Specifies the location of the password file containing the web services user's password; for instructions on how to set the password for this user.|
Specifies the endpoint used to obtain more event details when an Opr Event Change object is received; the default value is:
|OMI_REST_SYNC_EVENT_CHANGE_ ROOTPATH||Specifies the endpoint used to send Opr Event Change objects to HP OMi, which reflect response choices made by xMatters Users and are intended to update events accordingly; the default value is: /opr-gateway/rest/synchronization/event_change/|
|DEDUPLICATION_FILTER||Specifies the name of the filter used by the Integration Agent deduplicator module, which prevents duplicate events from being injected into xMatters; the default value is "hpomi-3-0". The deduplication filter is cleared whenever the Integration Agent is restarted; this means that after a restart, events that would otherwise be filtered may be injected into xMatters.|
|ANNOTATE_DELIVERY||Specifies whether xMatters should update the originating event with delivery annotations; the default value is "true".|
|XMATTERS_FORM||The web service URL of the "HPOMi" form imported as part of the communication plan; for instructions on how to retrieve this URL,|
|XMATTERS_FYI_FORM||The web service URL of the "HPOMi-fyi" form imported as part of the communication plan; for instructions on how to retrieve this URL,|
|INITIATOR||Specifies the web login ID of a separate xMattersuser for authenticating REST API requests. The user (or its role) must have permission to access the integration's forms via the REST API.|
|INITIATOR_PASSWORD_FILE||Specifies the location of the file containing the password of the xMattersinitiator user. This password file must be created using the IAPassword utility,|
|INITIATOR_USER_ID||Specifies the user ID of xMattersinitiator user that authenticates REST API calls.|
- Save and close the file.
- Restart the Integration Agent
This integration includes encrypted files, located in the <IAHOME>\conf folder, that store the passwords for the integration user and the HP OMi API user. You will need to update the file with the correct password for the SERVICE_DESK_USER variable specified in the hpomi-3-0\configuration.js file.
- Open a command prompt and navigate to <IAHOME>\bin.
- Run the following command, where <new_password> is the password for the web services user specified in the configuration.js file and <old_password> is the existing password (the default password for a newly installed integration is "password"):
iapassword.bat --new <new_password> --old <old_password> --file conf/.pwd
- Now run the command again, but where <new_password> is the password for the INITIATOR user specified in the configuration.js file and <old_password> is the existing password (the default password for a newly installed integration is "password"):
iapassword.bat --new <new_password> --old <old_password> --file conf/.initiatorpasswd
For more information about working with the iapassword command, and creating password files, refer to the xMatters Integration Agent Guide.
The integration package includes a file that engages the Integration Agent filtering and suppression module to suppress duplicate events (also know as deduplication). This can help to avoid disruption of traffic due to event floods (a potential hazard with improperly configured management systems).
The deduplicator is installed into the <IAHOME>\conf folder, and is configured by default to suppress up to 100 duplicate events for two minutes. You can configure the filter to extend the time period in which an event is considered to be a duplicate, the number of events within that period, and the tokens or properties that xMatters uses to determine what makes the event unique.
To enable deduplication:
- Navigate to the <IAHOME>/conf directory.
- If you have an existing deduplicator-filter.xml file in this folder, create a backup version in a separate location.
- Copy the deduplicator-filter.xml file from the integration-agent/conf folder in the extracted integration archive into the <IAHOME>/conf directory.
- Restart the Integration Agent.
For more information about the deduplication filter and the available settings, refer to the "Filtering and Suppression" section in the xMatters Integration Agent Guide.
To configure HP OMi to integrate with xMatters, you need to:
- Create a connected server.
- Create an event forwarding rule
Configuring a connected server allows notification responses to update events appropriately.
To create a connected server:
- In the HP OMi interface, on the Administration tab, in the Setup and Maintenance area, click Connected Servers.
- Click the New Item icon, and then select the External Event Processing server type. HP OMi displays the Create New Server Connection dialog box.
- On the General page, in the Display Name field, type xMatters, and then click Next.
- On the Server Properties page, type the fully qualified DNS name of the server on which the xMatters Integration Agent is installed, select Management System as the CI Type, and then click Next.
- On the Integration Type page, select Call External Event Web Service.
- In the Root URL Path field, type /http/applications_hpomi-3-0, and then click Next.
- On the Outgoing Connection page, ensure that the value in the Port field (default for the integration is 8081) matches the service-gateway port defined in the IAConfig.xml file.
- If the Integration Agent and xMatters have not been configured for SSL, clear the Use Secure HTTP check box.
- Select the Supports Synchronize and Transfer Control check box, and then click Next.
- On the Event Drill-down page, click Next.
- On the Incoming Connection page, enter the password specified in the configuration.js.
- Click Finish.
Each deployment of the integration requires a unique event forwarding rule, specific to each deployment, based on the organization's assessment of which events are appropriate to be sent to xMatters. An organization can choose to have more than one event forwarding rule, but for the integration to function correctly, an Event Forwarding rule must exist and be associated with the xMatters connected server.
The following steps provide an example of how to create a forwarding rule; the rule required for your integration will be a variation of this rule.
To create an event forwarding rule:
- In the HP OMi interface, click the Administration tab drop-down list, and then click Event Forwarding in the Automation section.
- On the Event Forwarding page, click the New Item icon. HP OMi displays the Create New Event Forwarding Rule dialog box.
- In the General section, in the Display Name field, type xMatters Event Forwarding Rule.
- In the Condition section, click the Browse button beside the Event Filter drop-down list.
- In the Select an Event Filter dialog box, click New, and then select New Simple Filter.
- In the Filter Configuration dialog box, in the Filter Display Name field, type xMatters Minor Severity Filter.
- Select the Minor Severity check box, and then clear the check box for all other severities.
- In the Correlation area, select All top level events, and then click OK.
- Once HP OMi returns you to the Select an Event Filter dialog box, with the xMatters Minor Severity Filter selected, click OK.
- In the Target Servers drop-down list, select xMatters, and then click Add target server (the plus symbol beside the drop-down list).
- In the Forwarding Type drop-down list, select Synchronize.
- Click OK.
When the integration is configured, HP OMi automatically sends information about any alarms it detects to xMatters via the Integration Agent. Try out triggering and responding to a notification to check that everything is working as you expect.
To test the incident notification portion of the integration, create a new alarm in HP OMi that targets a user with a device that you can access (so you can respond to the notification when it arrives). You can use the packaged sendEvent.bat script to inject a test event into HP OMi.
On Windows, this script is located at: C:\HPBSM\opr\support
For information on how to use the sendEvent.bat script, refer to the HP OMi documentation.
On a device with the xMatters mobile app, you can respond to the message simply by tapping Respond, and then selecting one of the response choices.
Other devices use similar methods: in an email notification, you would click a link in the message body; for an SMS, you would send an SMS reply containing a response option (or even a single digit).
For a voice notification, you would press a button on your phone to indicate your choice. If the message included a conference bridge request, the message is read aloud via the text-to-speech feature, and you would be prompted to join the conference. For example:
This is a manual conference bridge notification from HP OMi regarding INC0000054.
Message: The SAP system is throwing database errors.
Press 1 to join the conference, press 2 to ignore and stop notifying.
After you respond to the notification, you can see how the integration automatically updates the HP OMi event information with the response details:
When the response is received, the Lifecycle state is changed to In Progress and a message is logged in the Annotations tab of the event.
To view the notification results:
- Open the HP OMi Web Console.
- On the Event Perspective tab, under Event Browser, locate the event used for testing notifications.
- The Life Cycle State has changed to In Progress, indicating that the event was acknowledged from xMatters:
- To display the messages annotated to the event, click the Annotations tab.
- An annotation indicates that the event was changed to "In Progress" by the responder. For In Progress, Resolved, and Closed responses, the Assigned User is set to the person who responded.