The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

Introduction

This article provides installation, configuration, and implementation details when integrating xMatters with Cherwell.

Cherwell is a leading ITSM tool capable of advanced incident management. The interface provides a framework for building complex workflow with simple point and click – no coding! – widgets. When coupled with xMatters, this integration:

• Can notify the Owned By Team or the Owned By User about details of an incident.
• Can update the status and Owned By of the incident when a user responds to a notification.
• Can add device delivery and event status details to the Incident Journal in Cherwell.

The default integration configuration sends the following items from the incident to xMatters:

• Incident ID
• Short Description
• Description
• Status
• Priority
• Owned By Team
• Owned By
• Incident Object ID (used by the outbound integration to update the incident)
• Incident Rec ID (used by the outbound integration to update the incident)

The Cherwell workfow attached to this article contains the following inbound integrations:

• New Incident: This integration receives the HTTP POST from Cherwell and builds the event payload. It queries to make sure the targeted recipient exists and, if not, sets the recipient to null, forcing the event to target the recipient in the New Incident form. 
• Terminate Events: This integration parses the Incident ID and queries for all active events in xMatters with that Incident ID and then terminates them. 

The workflow also contains the following outbound integrations:

• Delivery Notifications: Updates the Incident Journal with device delivery information.
• Event Status Notifications: Updates the Incident Journal with event status information.
• Response Notifications: Updates the Incident Journal with responses from users and updates the Incident Status and Owned By fields if the response is "Assign to me".

How it works

Out of the box, the integration uses a One Step to map the fields from the Cherwell incident to parameters in xMatters. The One Step is manually triggered in the out-of-the-box mApp, but an Automation Process could be created to kick it off automatically. The One Step uses a web service to make an HTTP POST to the Integration Builder, which generates the event payload. Before creating the event, the script searches xMatters for the "Owned By Team" value and, if it exists in xMatters, targets that group. If not, it uses the entry in the New Incident form layout. The integration uses a similar process for the "Owned By" value. 

Before you begin

Before you configure the integration, there are a couple of things you can do ahead of time to make it easier. 

Download the integration components

To begin, download the workflow attached to this article and save it to a location on your local machine. Don't extract the contents - you'll import the zip file directly into xMatters.

Get the mApp

You also need the mApp from the Cherwell mApp Exchange. 

Configure Cherwell security for xMatters

Create an xMatters user in Cherwell

1. Navigate to the Security menu and click Edit Users.
2. Create a new user for the xMatters integration and note the Login ID and Password – you use these later to configure xMatters.
3. Set the Security Group as "IT Service Desk Manager" to enable updating of Incident records. 

Create a REST API client in Cherwell

In the Security menu, click Edit REST API client settings and create a new REST API client. Note the generated Client Key. This is used with the username and password above to authenticate into Cherwell from xMatters.

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Set up an integration user

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 instructions.

Note: Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration.

Create users and groups that will receive notifications

The integration notifies the group or user defined as the "Owned By" in the incident (if it is populated) or the Owned By Team. If these don't exist in xMatters, the integration targets the default recipient set in the form layout. 

For more information about creating users and devices in xMatters, refer to the xMatters online help.

Import the workflow

The next step is to import the workflow.

To import the workflow:

1. In the target xMatters system, on the Workflows tab, click Import.
2. Browse to the .zip file you downloaded, or drag it onto the Import Workflow dialog box
3. Click Import Workflow.
4. Click the gear icon beside the workflow and select Editor Permissions.
5. Add the integration user, and then click Save.
6. Click the workflow name to open the Forms tab.
7. For the New Incident form, in the Web Service drop-down list, click Sender Permissions.
8. Enter the integration user, and then click Save Changes.
9. Click Edit beside the New Incident form and select Layout.
10. In the Recipients area, specify a default recipient (a user or a group) for events, and then click Save Changes.

Update Response Map for New Incident One Step

You need to configure the inbound integration to use the UUIDs for the New Incident form responses. 

1. Go to the Forms tab.
2. Beside the New Incident form, click Edit and select Responses.
3. Click the API icon beside each response and copy the UUID to a text file.
   
4. Click the Integration Builder tab.
5. Click the New Incident One Step integration, then click Save and Open Script Editor.
6. Update the "responseMap" variable to point to the right UUIDs. 

Update the Cherwell endpoint

On the Integration Builder tab, click Edit Endpoints to display the available endpoints.

Click the Cherwell endpoint, and then update the Base URL, Access Token URL, Username (LoginID), Password and Client ID (the generated Client Key) with the appropriate values from Cherwell: (NOTE: Make sure you do not have a trailing slash (/) in the Access Token URL. IIS doesn't seem to like it). 

The Access Token URL is the base URL, with CherwellApi/token appended. 

If Cherwell is not accessible from the outside world, then you will need to install the xMatters Agent, behind your firewall. The Base URL value below will then need to be the address the agent uses to get to Cherwell. Additionally, the Outbound response scripts will need to be updated to use this agent. (See the next section)

Note: If Cherwell is not accessible from the outside world (i.e. from xMatters), then the Test Authentication will always fail. 

Configure outbound integrations (Optional)

This section is only required if Cherwell is behind a firewall, and you are using an xMatters Agent. 

To configure the outbound integrations to run on an agent:

On the Integration Builder tab, expand the Outbound Integrations and click on Delivery Notifications. In the Location section, change the drop down to select xMatters Agents and select the appropriate server:

Repeat for the Delivery Notifications and Response scripts. 

Configure Cherwell

Now that you've configured xMatters, you can configure Cherwell to integrate with xMatters. The following sections require you to log into Cherwell and access the Configuration page.

Import the mApp

1. Log in to the Administrator console.
2. Click mApps in the left-hand menu then click Apply a mApp.

2. Navigate through the wizard:

3. On the last step, select Open a Blueprint so that I can preview the changes, since you need to make additional changes before the mApp can be published, then click Finish.

4. Click Managers > Web Services to display the Web Services Manager. When the dialog is displayed, right-click on the xMatters Integration Builder and select Edit:

5. In the URL field, paste the hostname portion of the inbound integration URL (or just enter the hostname of your xMatters instance). 

6. Now click Methods, and then select the New Incident method and click Edit.
7. In the Endpoint field, paste the Integration URL portion of the New Incident One Step inbound integration URL.
   • The endpoint entry should not begin with a slash (/).
8. Click Add to add a new "Text" data type parameter and give it the name apiKey. 

9. Click OK, and then repeat steps 6-8 for the Terminate Event method, using the URL parts from the Terminate Events inbound integration.

10. Click OK and close the Web Services Manager.
11. Back on the blueprint page, click Managers > One-Step to display the One-Step Action Manager.
12. Click Global and then select xMatters - Notify and click Edit (or right-click and select Edit).
13. Select Call a web service. Under Method, highlight apiKey and select Set Value. Paste the API Key portion of the inbound integration URL into the value field.

14. Click OK then repeat steps 11-13 for the Terminate Event method. Close the One-Step Action Manager.
15. Save the Blueprint, then click Scan Blueprint on the left-hand menu. If that is successful, click the Publish Blueprint link.

Reload definitions

After you publish the blueprint, you're prompted to reload definitions.

1. Head over to the Cherwell desktop client (not the Administrator Console we were working in above).
2. Click Help and select Reload definitions.

Test the integration

First, make sure logging is turned on for the New Incident One Step inbound integration for better monitoring of the inbound event. (On the Integration Builder tab, expand the inbound integrations list, click the gear icon beside the New Incident One Step integration, and then select Activity Stream. On the Activity Stream page, click the Logging icon at the top of the page to turn logging on.)

To test the integration, create an incident in Cherwell, and open the One Step Manager. Select the xMatters - Notify One Step and click Run. This initiates a web service call to the xMatters Integration Builder. 

Troubleshooting

There are several places you can inspect when troubleshooting why an event doesn't seem to make it over to xMatters. 

• For help with the Integration Builder feature, refer to the Integration Builder section of the online help.

Inbound to xMatters

If events aren't getting into xMatters or an error is thrown in the Cherwell UI, the System Analyzer will have details on what happened. To fire up the System Analyzer, login to the Cherwell client as an admin and click Help > System Analyzer. Then, re-run the One Step or reproduce the issue. Click back into the System Analyzer and there will be detailed information on what happens on the Cherwell side. 

If there are no errors thrown on the Cherwell side, the next place to look is the Integration Builder Activity Stream. While on the Integration Builder tab, expand the Inbound integrations section, click the gear icon beside the intended integration service, and then click Activity Stream. 

The Activity Stream contains the incoming (and for outbound integrations, the outgoing) request, any logging statements, and the final event creation messages. 

Outbound from xMatters

For the two-way integration from xMatters to Cherwell, the primary source of logging is the Integration Builder Activity Stream for that particular integration.  

A curl request to retrieve the OAuth token can be helpful to ensure the username and password are correct, as well as make sure the network path is open. Execute this command on a box that can access the Cherwell server, make sure to replace the username, password and client_id with the appropriate values for your system. Keep the grant_type as "password":

curl -X POST --header "ContentType: application/x-www-form-urlencoded" -d 'username=andrew&password=pass&grant_type=password&client_id=7f7ab9c96-8af3-41cc-a5e9-fa1afdab631a' "http://cherwell.acme.com/CherwellApi/token"

If this is successful, then the username, password and client_id values are all valid. If it fails, inspect the error message for details.  

Download resources