Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/xmatters/xm-labs-remedy-helix-onprem-ondemand

Last synced: about 1 month ago
JSON representation

Host: GitHub
URL: https://github.com/xmatters/xm-labs-remedy-helix-onprem-ondemand
Owner: xmatters
License: mit
Created: 2019-12-02T15:33:33.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2023-01-11T20:54:52.000Z (about 2 years ago)
Last Synced: 2024-11-06T08:30:46.668Z (3 months ago)
Size: 8.39 MB
Stars: 1
Watchers: 2
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# BMC Helix ITSM Incident Flow Designer Integration
Notify on-call response teams when critical incidents are reported in Helix ITSM. With the xMatters and BMC Helix ITSM (Cloud or On-premise) closed-loop integration, the on-call members of resolver teams are automatically notified via multiple communication channels. When the recipient responds, notes are added to the incident work log and specific incident actions may take place depending on the response.

# Pre-Requisites
* Version 19.08 or later of Helix ITSM Cloud or On-premise (on-premise uses the xMatters Agent)
* Note, this integration version includes support for version 19.02, and earlier, which POSTs to xMatters using SOAP/XML
* Account in BMC Helix ITSM
* xMatters account - If you don't have one, [get one](https://www.xmatters.com)!

# Files
[BMCHelixITSMIncident76.zip](BMCHelixITSMIncident76.zip) - download this Workflow to get started
[BMCRemedyHelix_19-08_defs.zip](BMCRemedyHelix_19-08_defs.zip) - download this zip file containing the BMC Helix ITSM workflow definition files

# How it works
Helix ITSM triggers one of the xMatters filters as part of the integration. The filter POSTs the Helix ITSM Incident ID to xMatters, and in turn xMatters uses a Helix ITSM REST API to get the incident properties and subsequently creates the xMatters Event targeted to the assigned resolver Group.

The notified resolver responds with Assign to me - to take ownership of the incident or Escalate - to escalate to the next resource in the on call schedule.

The closed loop integration annotates the incident work info with xMatters event status, notification delivery status, user responses and user comments. Additionally, an Assign to me response assigns the user to the incident and updates the incident status to In Progress.

# Installation

## xMatters set up
### Create a REST integration user account

### Install xMatters Agent for integration with Helix ITSM On-Premise
* On the Helix ITSM Mid-Tier Server, where the xMatters Agent is to be installed, open a browser and log in to xMatters. In xMatters on the *Workflows* page in the left navigation bar click **Agents**
* Select the OS of the server from the drop-down list
* Click **Download this version**
* Choose a proxy configuration
* Follow the instructions provided in Step 3
* The xMatters Agent will be installed on the server and the service will automatically start

### Import the Workflow
* Import the **BMC Helix ITSM | Incident | 7.6** (BMCHelixITSMIncident76.zip) Workflow https://help.xmatters.com/ondemand/xmodwelcome/workflows/manage-workflows.htm

### Assign permissions to the Workflow and Form
* On the *Workflows* page, click the Edit drop-down menu for the **BMC Helix ITSM | Incident | 7.6** then select **Editor Permissions**
* Add any users, groups and/or roles to have editor permissions to this workflow
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Forms**
* Click the **Web Service** drop-down menu for the **Incident Alerts** form
* Select **Sender Permissions** then add the xMatters REST integration user

### Configure List Property Values
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Properties**
* Verify/Edit the values in the following list properties so they match available values from Helix ITSM:
Priority

### Configure Endpoints and Constants
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Flows**
* Click **Incident Alerts Workflow**
* Click the **Components** drop-down button in the upper right then select **Endpoints**
* For the Helix ITSM endpoint, type the **Base URL** for the BMC Helix ITSM environment, for example *https://customer-restapi.onbmc.com* then **Save** then **Close**
* Click the **Components** drop-down button in the upper right then select **Constants**, then edit these constants:

| Constant | Description |
|:------------------------------- |:--------------------------------------------------------------------------------- |
| HELIX_FQDN | Fully qualified domain name of the Helix ITSM Mid-Tier Server |
| HELIX_OPT_SIMPLE_GROUP_NAME | true to use simple group names or false to use Company\*Org\*Group |
| HELIX_SERVER_NAME | Helix ITSM logical server name |
| XMATTERS_INCIDENT_EVENT_IB_PATH | Inbound Integration path (URL Auth) to Step 02 |
| XMATTERS_INCIDENT_IB_FLOW_PATH | Inbound Integration path (URL Auth) to Step 01 (only reqd when using an xM Agent) |

### Get the XMATTERS_INCIDENT_EVENT_IB_PATH
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Integration Builder**
* Click the **4 Configured** link for Inbound Integrations
* Click the **Step 02 | Create Event | Incident Alert | Flow** link
* Scroll to the **How to trigger the integration** section then click **Select method** and **URL Authentication**
* In **Authenticating User** begin typing the username for the REST integration user in xMatters and select the user
* Click **Copy** to copy the URL displayed in *Trigger*
* Be sure to remove everything before `/api/integration/` after pasting in the Constant **XMATTERS_INCIDENT_EVENT_IB_PATH**

### Get the XMATTERS_INCIDENT_IB_FLOW_PATH (only required if using an xM Agent in the integration)
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Integration Builder**
* Click the **4 Configured** link for Inbound Integrations
* Click the **Step 01 | Helix Inbound Request | JSON** link
* Scroll to the **How to trigger the integration** section then click **Select method** and **URL Authentication**
* In **Authenticating User** begin typing the username for the REST integration user in xMatters and select the user
* Click **Copy** to copy the URL displayed in *Trigger*
* Be sure to remove everything before `/api/integration/` after pasting in the Constant **XMATTERS_INCIDENT_IB_FLOW_PATH**

### Verify Flow Designer steps
Some Flow Designer steps are configured with a **Run Location** of either **Cloud** for Helix ITSM On-Demand or **xMatters Agent** for Helix ITSM On-Premise
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Flows**
* Click **Incident Alerts Workflow**
* Verify the **Run Location** for all steps on the Flow Designer canvas with labels as identified below:
Helix | Add Assignee | Incident
Helix | Add Work Info | Incident
Helix | Get Incident

## BMC Helix ITSM set up
Configuring BMC Helix ITSM to integrate with xMatters requires the following steps:

* Import the workflow definition files
* Configure filters
* Configure the ITSM user
* Disable automatic assignments

### Importing workflow definition files
* Log in to the BMC Helix ITSM Developer Studio, and then select **File** > **Import**
* Select **BMC Helix ITSM Developer Studio** > **Object Definitions**, and then click **Next**
* Select the AR System server into which you want to upload the integration objects, and then click **Next**
* Do one of the following:
Type in the location of the `xm_foundation_REST.def` file
Click the Browse button to the right of the text field and navigate to the location of the `xm_foundation_REST.def` file. Select the file, and then click **Open**.
* Click **Next**
If you have already imported a workflow definition file, ensure that you select the Replace Objects on the Destination Server check box (do not select the other check boxes), but note that any changes you have made to those objects will be lost. If you are sure the changes you made are necessary for your installation, you will be required to re-apply those changes to the new version of the files being imported unless you applied those changes to overlay objects.
* Repeat the above steps to import the `xm_incident_REST.def` file.
Note this file must be imported after the foundation file.
Click **Finish**

### Configuring filters
The integration includes a filter and an escalation that use the Set Fields action to consume a web service; these objects need their endpoints changed to the address of the appropriate (JSON or XML) *Step 01 | Helix Inbound Request* inbound integration for On-Demand or to the address of the xMatters Agent for On-Premise.
Filter: XM:EI:EventInjection_100

#### For Helix ITSM On-Demand (v19.08 or later), get the endpoint URL
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Integration Builder**
* Click the **4 Configured** link for Inbound Integrations
* Click the **Step 01 | Helix Inbound Request | JSON** link
* Scroll to the **How to trigger the integration** section then click **Select method** and **URL Authentication**
* In **Authenticating User** begin typing the username for the REST integration user in xMatters and select the user
* Click **Copy** to copy the URL displayed in *Trigger*
* Paste the full URL as the endpoint in the Helix ITSM filter

#### For Helix ITSM On-Demand (v19.02), get the endpoint URL
* On the *Workflows* page, click the **BMC Helix ITSM | Incident | 7.6** then click **Integration Builder**
* Click the **4 Configured** link for Inbound Integrations
* Click the **Step 01 | Helix Inbound Request | XML** link
* Scroll to the **How to trigger the integration** section then click **Select method** and **URL Authentication**
* In **Authenticating User** begin typing the username for the REST integration user in xMatters and select the user
* Click **Copy** to copy the URL displayed in *Trigger*
* Paste the full URL as the endpoint in the Helix ITSM filter

#### For Helix ITSM On-Premise, get the endpoint URL for the xMatters Agent
* On the Workflows page, click the **BMC Helix ITSM | Incident | 7.6** then click **Integration Builder**
* Click the **4 Configured** link for Inbound Integrations
* Click the **Step 00 | Incoming Helix | xM Agent** link
* In **Integration Settings** *Step 1*, select **xMatters Agent** in **Location** and select the appropriate Agent
* Scroll to the **How to trigger the integration** section then click **Select method** and **URL Authentication**
* In **Authenticating User** begin typing the username for the REST integration user in xMatters and select the user
* Click **Copy** to copy the URL
* Paste the full URL as the endpoint in the Helix ITSM filter

### Configuring ITSM user
The integration requires a dedicated ITSM user to interact with incidents.

#### Create an ITSM user
First, create a new ITSM user with the Incident Master role in BMC Helix ITSM; the user does not need to be Support Staff.

**Note: If you specify a Login ID of "xmatters" for this ITSM user, you can skip the following two update steps.**

#### Update the filter qualification
The XM:Incident_Re-Assigned_899 filter contains the following qualification criteria: `($USER$ != "xmatters")`

This qualification prevents the integration from sending a second notification based on an incident's assignment changing because of a user response to an earlier notification. Replace `xmatters` with the name of the ITSM user created in Step One.

#### Update the default assignee
The out-of-box permissions allow the Submitter and Assignee (and BMC Helix ITSM administrators) to search instances of the XM:Event Injection form. This allows users who modify incidents to see the corresponding XM:Event Injection instance for their update. To allow the ITSM user to also see all the Event Injection forms, modify the default value for the Assigned To field to the ITSM user you created.

### Disabling automatic assignment
To allow xMatters to control assignments, you must turn off the automatic assignment feature in BMC Helix ITSM.

**Note: To perform this step, you will need to login as a user with Administrator permission.**

* Log in to the BMC Helix ITSM Mid Tier web server.
* Click **Applications**, and then click the **Administrator Console** left-menu item.
* Click **Application Administration Console**.
* On the **Custom Configuration** tab, expand **Incident Management**, and then expand **Advanced Options**.
* Select **Rules**, and then click **Open**.
* Click the **New search** button then click the **Search** button to perform a search for all existing "Incident Rules".
* For each existing rule, do the following:
Select the rule, and in the **Assignment Process** drop-down list, select **(clear)**.
Click **Save**.
Alternatively, you can set **Assignment Engine Integration** to "No", then **Save**.

# Testing

## Triggering a notification
To trigger a notification, create a new incident with a priority of High or Critical in BMC Helix ITSM, and assign it to
a user or group that exists in both BMC Helix ITSM and xMatters:

## Responding to a notification
In the following example, the notification is received on an Apple iPhone, but the process is similar for all devices.

* Notifications appear in the application Inbox

* Opening the notification displays the details

* After viewing the details, either click the respond (blue return arrow) icon at the top or scroll to the bottom of the notification

* Tap the desired response, then tap **Respond now** or **Respond with comment**

# Troubleshooting
If an xMatters notification was not received you can work backwards to determine where the issue may be:
* Review the xMatters Reports tab and the specific [Event Log](https://help.xmatters.com/ondemand/installadmin/reporting/eventlogreport.htm)
* If no Event was created, review the [xMatters Workflows Flow Designer Activity Panel](https://help.xmatters.com/ondemand/xmodwelcome/flowdesigner/activity-panel.htm)
* If no activity was recorded, in Helix ITSM review the XM:Event Injection Form and the XM:Action Form and the Helix ITSM logs for a POST to xMatters.