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.
This article provides installation, configuration, and implementation details when integrating xMatters On-Demand 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
- 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 communication plan 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 communication plan 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".
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 configure the integration, there are a couple of things you can do ahead of time to make it easier.
To begin, download the communication plan 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.
You also need the mApp from the Cherwell mApp Exchange.
- Navigate to the Security menu and click Edit Users.
- Create a new user for the xMatters integration and note the Login ID and Password – you use these later to configure xMatters.
- Set the Security Group as "IT Service Desk Manager" to enable updating of Incident records.
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.
The first step in setting up your integration is to configure xMatters.
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.
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 communication plan's form layout.
For more information about creating users and devices in xMatters, refer to the xMatters On-Demand help.
The next step is to import the communication plan.
To import the communication plan:
- In the target xMatters system, on the Developer tab, click Import Plan.
- Click Choose File, and then locate the downloaded communication plan (.zip file).
- Click Import Plan.
- Click the Edit drop-down list for the plan, and select Access Permissions.
- Add the integration user, and then click Save Changes.
- In the Edit drop-down list, select Forms.
- For the New Incident form, in the Web Service drop-down list, click Sender Permissions.
- Enter the integration user, and then click Save Changes.
- Click Edit beside the New Incident form and select Layout.
- In the Recipients area, specify a default recipient (a user or a group) for events, and then click Save Changes.
Next, you need to configure the authentication for the inbound integration and retrieve the URLs for each inbound integration to configure Cherwell.
To configure an inbound integration and retrieve its URL:
- In the Integration Builder, expand the list of inbound integrations.
- Click the name of the integration to view its details.
- Make sure the authentication method is set to URL Authentication.
- Note: This is a change to how we previously recommended you set up the integration.
- Scroll down to How to trigger the integration at the bottom of the page, and select the integration user as the authenticating user.
- To be able to select the integration user, you need to be a supervisor of that user and the user needs to be assigned to the REST Web Services role.
- Click Copy beside the Trigger field to copy the URL for the inbound integration to your clipboard:
Prepare the URLs
To make it a little easier to configure the Cherwell portion of the integration, you might want to prepare the URL now. To do this, paste the URL from the inbound integration into a text editor, and then cut it into three parts:
- Hostname: The part of the URL that identifies your xMatters instance (for example, https://example.xmatters.com)
- Integration URL: The portion of the trigger URL that identifies the inbound integration (for example, api/integration/1/functions/long-string-of-letters-and-numbers/triggers)
- API Key: The special key at the end of the URL created to identify the authenticating user.
Here's where those three parts are in the URL:
You need to configure the inbound integration to use the UUIDs for the New Incident form responses.
- Go to the Forms tab.
- Beside the New Incident form, click Edit and select Responses.
- Click the API icon beside each response and copy the UUID to a text file.
- Click the Integration Builder tab.
- Click the New Incident One Step integration, then click Save and Open Script Editor.
- Update the "responseMap" variable to point to the right UUIDs.
On the Integration Builder tab for the communication plan, 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.
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.
- Log in to the Administrator console.
- Click mApps in the left-hand menu then click Apply a mApp.
- Navigate through the wizard:
- 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.
- 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:
- In the URL field, paste the hostname portion of the inbound integration URL (or just enter the hostname of your xMatters instance).
- Now click Methods, and then select the New Incident method and click Edit.
- 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 (/).
- Click Add to add a new "Text" data type parameter and give it the name apiKey.
- Click OK, and then repeat steps 6-8 for the Terminate Event method, using the URL parts from the Terminate Events inbound integration.
- Click OK and close the Web Services Manager.
- Back on the blueprint page, click Managers > One-Step to display the One-Step Action Manager.
- Click Global and then select xMatters - Notify and click Edit (or right-click and select Edit).
- 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.
- Click OK then repeat steps 11-13 for the Terminate Event method. Close the One-Step Action Manager.
- Save the Blueprint, then click Scan Blueprint on the left-hand menu. If that is successful, click the Publish Blueprint link.
After you publish the blueprint, you're prompted to reload definitions.
- Head over to the Cherwell desktop client (not the Administrator Console we were working in above).
- Click Help and select Reload definitions.
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.
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.
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.
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.