Cherwell On-Premise xMatters Integration

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 Journal Entries to the Incident Record detailing what xMatters is doing.
• Can terminate the xMatters event when it is resolved in Cherwell.
• Once an event is sent to xMatters Integraiton Agent a Cherwell REST API Get Incident and Get Task call allows for passing any incident or task field to xMatters. Included Communication Plan will need to be modified to accomodate any additional fields passed to xMatters.
• A Cherwell webservice Onestep object or and Email can be used to trigger the xMatters event.
• Parse Email Outbound Integration script included to break up email body for email initiated events.

xMatters Communication Plan Inbound Integrations:

• New Incident One Step: This integration receives the HTTP POST from Integration Agent 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.

xMatters Communication Plan Outbound Integrations:

• Event Delevery Notifications (IA): Updates the Incident Journal with devlivery information. This has been tested to work but has not been tested extensively.
• Event Status Notifications (IA): Updates the Incident Journal with event status information.
• Response Notifications (IA): Updates the Incident Journal with responses from users and updates the Task Status and Owned By fields if the response is "Assign to me".

Pre-Requisites

• Virtual Machine running the newest version of the xMatters Integration Agent
• Cherwell On-Premise v8 +
• xMatters account - If you don't have one, get one!

Files

• CherwellOnPremise.zip - This the Cherwell On-Premise Communication plan.
• Cherwell_IS_Package.zip - This the xMatters Integration Service for use with the Integration Agent.

How it works

Out of the box, the integration uses a One Step to initiate a webservice call with the record id's from Cherwell Incident and Task records to the xMatters Integration Agent. The web service makes an HTTP POST to the Integration Agent, which generates the event payload and passes it to xMatters inbound integration.

The Integration Agent uses Cherwell REST API to GET Incident and Task properties from Cherwell. This is used to avoid known bugs in cherwell webservice OneStep when fields contains certain special characters.

After retreiving Cherwell property values, the New Incident One Stop inbound integration is targeted from the Integration Agent. An Automation Process is used to kick off the Cherwell One Step automatically when specified criteria are met. This can be customized to whatever criteria you see fit for your usecase. This integration was designed for Automation Processes that kickoff for all Tasks related to Priority 1 and 2 Indicents.

Before creating the event, the integration builder script will check the Assigned Group set in Cherwell is not empty. If the Assigned Group is empty, xMatters will target a hard coded group defaulted to Service Desk. This group can be changed as required.

This integration will initiate an xMatters Notification when an incident Task Record is created. It will update assigned user to the Incident Task, not the Incident Record.

See Integration Service Script cherwell.js Line 374 for instructions on how update incident record instead of task record when a user reponsonds to xMatter event.

The integration is set up to pass the following values from Cherwell to xMatters:

Incident Record Values:

• Incident ID
• Short Description
• Description
• Category
• Subcategory
• Priority
• Service

Task Record Values:

• Task ID
• Assigned Group
• Status

See Integration Service Script cherwell.js Line 108 for instructions on how to add additional parameters.

Installation

Details of the installation go here.

xMatters set up

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

Create an integration user

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:

1. Log in to the target xMatters system.
2. On the Users tab, click the Add New User icon.
3. Enter the appropriate information for your new user. Example User Name cherwell_API_User
4. Assign the user to the REST Web Service User role.
5. Click Save.
6. On the next page, set the web login ID and password.

Make a note of these details; you will need them when configuring other parts of this integration.

This users details will be user for constants in the Integration Services Configuration Script: INITIATOR and PASSWORD

Create users and groups that will receive notifications

The integration will notify the group or user defined as the "Owned By Team". If this recipient doesn't exist in xMatters, a hard coded group (Defaulted to "Service Desk") inside of the inbound integration New Incident One Step. This group can be changed as required.

You can change this on lines 35 to 41 of Inbound Integration New Incident One Step.

DEVELOPER tab -> Cherwell (On-Premise) communication plan -> Edit Integration Builder -> Inbound Integrations -> New Incident One Step

This integration does not synchronize users and groups. Make sure you have created your users and groups in xMatters before using this integration.

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

Import the xMatters Communication Plan

The next step is to import the communication plan.

To import the communication plan:

1. In the target xMatters system, on the Developer tab, click Import Plan.
2. Click Browse, and then locate the downloaded communication plan: CherwellOnPremise.zip
3. Click Import Plan.
4. Once the communication plan has been imported, click Plan Disabled to enable the plan.
5. In the Edit drop-down list, select Forms.
6. For the New Incident form, in the Not Deployed drop-down list, click Create Event Web Service.
7. After you create the web service, the drop-down list label will change to Web Service Only.
8. In the Web Service Only drop-down list, click Permissions.
9. Enter the REST API user you created above, and then click Save Changes.

Accessing web service URLs

Each integration service has its own URL that you can use to target it from Cherwell.

To get a web service URL for an integration service:

1. On the Integration Builder tab, expand the list of inbound integrations.
2. Click the gear icon beside the integration service you want to target, and then select Integration URL.
3. If Authentication is required, click the Lock icon and note the username and password credentials. They will be needed later.

You will need the URL for each integration service when configuring Cherwell.

Create Integration Services

This integration uses an integration services that need to be created on the "applications" event domain.

To create the integration services:

1. In xMatters, on the Developer tab, click Event Domains.
2. In the Event Domains list, click the applications link.
3. On the Event Domain Details page, in the Integration Services section, click the Add New link.
4. On the Integration Service Details page, in the Name field, type "cherwell" and then click Save.
5. Click the Add New link again.

Configure the xMatters Integration Agent

Now that you've configured xMatters On-Demand, it's time to configure the integration agent

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 please follow this link to download, deploy, and configure:

Integration Agent for xMatters 5.x & xMatters On-Demand

Install the Integration Service package

The Cherwell Integration Service package contains all that you need to configure the Cherwell On-Premise integration to work with the integration agent.

To install the package:

1. Extract Cherwell Integration Service Package Cherwell_IS_Package.zip to get a folder named integrationservices.

2. Copy the integrationservices folder to the installation directory of the integration agent: for example: C:\xMatters\integrationagent-5.1.5

   • This folder is referred to as <IAHOME> in the remainder of the instructions.

3. Open the /conf/IAConfig.xml file and add the following line to the "service-configs" section (Around line 330):

<path>/applications/cherwell/cherwell.xml</path>

4. Save and close the file.

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.

Create xMatters User in Cherwell

Navigate to the CSM Administrator > Security menu and click Edit Users. Create a new user and note the Login ID and Password. Set the Security Group as "IT Service Desk Manager" to enable updating of Incident records. You can set the Security Group differently as long as the group has access to update appropriate tables.

Set up Cherwell API Client Key

1. Go to CSM Administrator > Security menu, click Edit REST API client settings.

2. Click the Green Plus Icon.

3. Provide the following settings:

   • Name: xMatters
   • Culture: Default / English
   • Token Lifespan: 20 minutes
   • Refresh Token Lifespan: 1440 minutes
   • API Access is Enabled: True
   • Allow Anonymous Access: False

4. Take note of the Client Key you will need this when configuring the Integration Service Configuration.js file.

Create Web Service to Trigger xMatters Integration Agent

1. Open the Web Service Manager.

   • From the CSM Administrator Main window, click the Browser and Mobile category, and then click the Web Service Manager task.
   • From within a One-Step (create a One-Step > add a Call a Web Service One-Step Action), click the Ellipses button .

2. Select a scope and subfolder (if needed) for the Web service.

3. Click the Create New button Create New Button.

The Web Service Options window opens, displaying two pages (General and Methods; Accounts appears later if you select to use Basic Security).

4. Click the General page.

5. Define general properties for the web service:

   • Name: xMatters Integration Agent
   • Description: Web Service for calling xMatters Integration Agent
   • Service Type: WSDL (SOAP 1.1)
   • Security Type: None
   • WSDL URL: This will automatically populate

URL: http://Integration_Agent_URL/http/applications_cherwell

• URL should start with http://
• The Integration_Agent_URL should contain an ip address and a port number. Example: 178.19.1.32:8081
• Integration_Agent_URL should include /http/applications_cherwell at the end

Complete Web Service URL Should look as follows: http://178.19.1.32:8081/http/applications_cherwell

The Integration Agent URL can be found by:

  1. Go to DEVELOPER tab.
  2. Click Agents.
  3. Click INSTALLED tab.
  4. Click Show Details.

6. Click the Methods page.

7. Define a Web Service Method:

   1. Click the Add... button to add a Method.

   2. Define properties for the Methods:

      • Name: IntegrationServiceRequest
      • Result Type: None
      • Request Type: POST

3. Add a new Parameter to the Web Service Method by clicking:

   1. Click Add...

   2. Define properties for the Web Service Parameter:

      • Name: IntegrationServiceRequest
      • Data Type: Text
      • Parm Type: Standard

  3. Click OK

4. Completed Web Service Method Should look as follows:

5. Click OK. This will close the Web Service Method dialogue.

6. Completed Methods should look as follows:

9. Click OK. This will save a new Web Service Option with the name xMatters Integration Agent.

Create a new Cherwell One-Step

1. Open the One-Step Manager:

   From the CSM Desktop Client menu bar, click One-Step > One-Step Manager.
   
   
   

   From the Browser Client menu bar, click One-Step > One-Step Manager.
   
   
   

   From the Blueprint Editor menu bar_ in CSM Administrator, click Managers > One-Step.
   
   
   

2. Select Global scope.

3. Select a Business Object Association: Incident

   
   
   

4. Click the Create New button Create .

5. Provide a Name and Description for the One-Step.

   • Name: xMatters Integration Agent

   • Description: Trigger xMatters Integration Agent Web Service

     
     
     

6. Click OK.

   The One-Step Editor opens.

7. Define Conditions for when you want this one step to run.

   It is recommended to leave these settings along as an Automation Blueprint will be used to trigger the one-step.
   
   
   

8. Add a Call a Web Service Action to the Designer Board.

   Advanced Actions -> Call a Web Service
   
   
   The One Step should look as follows:
   
   
   

9. Select the Call a Web Service Action.

10. Click General page.

11. Define the General properties for the Call a Web Service Action.

    • Name: Call a xMatters Web Service
    • Service: Click the Ellipses button then select the xMatters Integration Agent Web Service we created earlier. See: Create Web Service to Trigger xMatters
      
      
      

12. Click the Method Page.

13. Specify the Method to call on the web service:

    • In the Method drop-down, select IntegrationServiceRequest.
      • The Parameters tree will show all the parameters for the selected method.

14. Select IntegrationServiceRequest in the Parameter tree.

15. Define the IntegrationServiceRequest Method Parameter:

    1. Select Set Value.

    2. Specify the following Value:

    <Incident_Rec_ID>Incident.RecID</Incident_Rec_ID>
    <Incident_ID>Incident.Incident ID</Incident_ID>
    <Task_Rec_ID>Task.RecID</Task_Rec_ID>
    <Task_Rec_ID>Task.Task ID</Task_Rec_ID>
    

    Important Note:

    • The values inside of <> MUST REMAIN exactly as they are above. These are referenced in the integration service script.
    • If these values are modified, the integration service script will need to be modified.
    • You will need to insert the Cherwell Reference Tokens <>Reference.Token</> yourself. Copy and pasting the value from above to Cherwell will not work.
      • You can insert a Cherwell Reference Token with the Selector button .
    
    
    3. Click Save Button (Top Left corner).

16. Click OK (Bottom Right corner).

    The One-Step will be Save and return you to the One-Step manager where you will see the new One-Step.

Create an Automation Process for Initiating and Terminating xMatters events.

You will need to follow this process TWICE. Once for Initiating and once for Terminating xMatters events.

1. From the CSM Administrator main window, click the Automation Process category and then click Create a New Automation Process Blueprint.

2. Click the New button and select Simple Action/Event Process.

   The Simple/Event Process window opens.

   
   
   
   

3. Define General Properties:
   

   Initiating xMatters Events

   • Name: xMatters Notify Team on Incident
   • Description: Initiate xMatters Integration Agent One-Step to notify with xMatters.
   • Business Object: Task
   • Execution Priority: Normal / Your preference
   • Event: Task Created
   
   

   Terminating xMatters Events

   • Name: xMatters Task Resolver Found
   • Description: Intiate xMatters Integration Agent One-Step to terminate xMatters event.
   • Business Object: Task
   • Execution Priority: Normal / Your preference
   • Event: Task Status Changed / Task User Assigned

This step will define when the Onestep which sends a webhook to the xMatters Integration should takes place.

You can set the values of these based on your specific requirements.

If you do not use Tasks as part of your incident notification process, you can modify the Automation Process to trigger off Incidents or whatever you desire.

Keep in mind, changes may be required in the Integration Services Script if you change this from a Task trigger.

4. Define Limit Records section.

   Limit when the xMatters integration is triggered.

   For further information on how to limit records that trigger automation process see Cherwell Documentation here.
   

5. Click Action page.
   
   
   

6. Define a One-Step to run when the event takes place:

   1. Select the One-Step radio button. The One-Step Field and Ellipses button become active.

   2. Click the Ellipses button to open the One-Step Manager, and then select xMatters Integration Agent One-Step created previously. See: Create a new Cherwell One-Step

7. Click OK.

Configure the Integration Service Package

Open the configuration.js file found in the

<IAHOME>\integrationservices\applications\cherwell folder and set the values for the following variables:

Configuration Variable	Description
WEB_SERVICE_URL	The Web Service URL of the "New Incident One Step" xMatters inbound integration (see Accessing web service URLs, above)
XMATTERS_ONDEMAND	The base URL of your xMatters instance. Do NOT include trailing slash. Example: https://company.xmatters.com
WEB_SERVICE_TERMINATE_URL	The Web Service URL of the "Terminate Events" xMatters inbound integration (see Accessing web service URLs, above)
Cherwell Parameters
The values in the configureation.js file are most likely already correct. It is advised however to double check these values.
CHERWELL_JOURNAL_TYPEID	Replace with Your Cherwell Journal TypeID if it is different
CHERWELL_JOURNAL_TYPENAME	Replace with Cherwell Journal Type Name if it is different
CHERWELL_INCIDENT_OBJID	Replace with Cherwell Incident Business Object ID if it is different
CHERWELL_TASK_OBJID	Replace with Cherwell Task Business Object ID if it is different
CHERWELL_SERVER	The base URL of your Cherwell On-Premise Server. Do not inlude trailing slashes.
Webservice Parameters
INITIATOR	The User ID of the REST API user you created in xMatters. (see Create an Integration User, above).
PASSWORD	Path and filename of the password file containing the encrypted REST API user's password. For more information about creating this file, refer to the xMatters integration agent guide. The password is what was set in Create an Integration User, above.
CHERWELL_WS_ID	The Cherwell API Client Key (see Set up Cherwell API Client Key, above).
CHERWELL_WS_USER	The Cherwell User Name created so xMatters can authenticate into Cherwell (see Create xMatters User in Cherwell, above).
CHERWELL_WS_PASSWORD	The Cherwell User Password created so xMatters can authenticate into Cherwell (see Create xMatters User in Cherwell, above).