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 will send 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 contains the following inbound integrations:
- New Incident One Step: This integration receives the HTTP POST from Cherwell and builds the event payload. It will query to make sure the targeted recipient exists and, if not, will set 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 the xMatters Integration Builder web service. 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 will search xMatters for the "Owned By Team" value and if it exists in xMatters will target 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 get started configuring 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 extract it to a location on your local machine. Some of the instructions in this article will reference specific folders within the extracted integration archive.
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 injecting events.
This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the permissions and capabilities.
Note: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.
To create an integration user:
- Log in to the target xMatters system.
- On the Users tab, click Add.
- Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in the reports and Communication Center, you may want to identify the user as specific to Cherwell. For example:
- First Name: Cherwell
- Last Name: Integration
- User ID: cherwell
- Assign the user to the REST Web Service User role.
- Make a note of the user ID and the password you choose; you need them when configuring other parts of this integration.
- Click Add.
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 you created above, 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 you configured above, 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.
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:
- Navigate to the Integration Builder tab for the communication plan, and expand the list of inbound integrations.
- Click the name of an integration.
- In the Select authentication method section, select Basic in the drop-down, and then click Update Inbound Integration.
- NOTE: URL Authentication is not supported by this integration.
- Scroll down to the bottom of the page and click the Copy URL link to copy the URL for the inbound integration to your clipboard:
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 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:
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 and click the mApps icon then click the Apply a mApp link.
- Navigate through the wizard and take the defaults.
- Select "Open a Blueprint..", since you need to make additional changes before the mApp can be published.
- When the blueprint is displayed, click Managers > Web Services ... to display the Web Services Manager. When the dialog is displayed, right click on the xMatters Integration Builder and hit Edit:
- Update the URL to match the target xMatters instance.
- Note: In the Security Type drop-down, select Basic; a new icon will appear. Create a new account using the username and password of your integration user.
- Then click on the Methods icon on the left side and click Edit for the New Incident method.
- Update the Endpoint path to be the URL of the New Incident One Step inbound integration in xMatters. (Note that the endpoint should not begin with a /).
- Then do the same for the Terminate Event method, using the URL for the Terminate Events inbound integration.
- Click OK and close the Web Services Manager. Save the Blueprint, then Scan and Publish it.
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 xMatters On-Demand online help: Integration Builder.
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.