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 technical details for the implementation of the xMatters On-Demand service for use with ServiceNow Geneva, Helsinki, and Istanbul.
xMatters for ServiceNow is a direct, cloud-to-cloud integration, leveraging the communication plan technology within xMatters On-Demand to become the voice and interface of an automation engine. When ServiceNow detects something that requires attention, xMatters places phone calls, send emails or notifies your mobile app.
How it works
The integration consists of a pre-configured communication plan, and the xMatters application within ServiceNow which includes the following components:
- The synchronization component, which synchronizes users, groups and group members to xMatters.
- The incident notification component, responsible for handling incidents from ServiceNow to xMatters and from xMatters to ServiceNow.
- The Engage with xMatters component, which handles ad hoc communications, including conference bridges with xMatters.
The components use different sets of business rules, script includes and web services to accomplish their tasks. Each of the components is based on a trigger on a business rule; these triggers are set for Insert, Update, and Delete. After the change has been committed, initial checking within the business rules determines what type of operation has occurred. A call is then made to the script include, which processes the request and runs various rules based on the Incident Notification, Engage with xMatters, and Data Sync Configuration pages to determine what type of action to take.
If the script include determines that an action is to be sent to xMatters, it creates a ServiceNow REST message for incident events, or an xM API REST message for synchronization requests. ServiceNow REST messages are received by the communication plan, where the appropriate notification layout is determined based on the target device. xM API messages are received by the xMatters REST operations, and devices, users, or groups are added, updated, or deleted appropriately.
This integration installs new roles into ServiceNow to control interactions between users and integration components.
- x_xma_xmatters.xmatters_admin: Only users with this role can modify xMatters components within the ServiceNow interface.
- x_xma_xmatters.xmatters_rest: This role must be assigned to a ServiceNow API user to successfully access the REST endpoint and execute the required integration requests. See the "ServiceNow API User" section, below.
- x_xma_xmatters.xmatters_engage: Users with this role can use the Engage with xMatters feature described below. Assigning this role to a group will automatically assign it to all users within a group, or you can add this role to an existing role to automatically assign it to multiple users. (You should also assign this role to the ServiceNow API user so they can update the Engage with xMatters records.)
- x_xma_xmatters.xmatters: Assign this role to any users or groups you want to synchronize into xMatters. Assigning this role to a group will automatically assign it to all users within a group, or you can add this role to an existing role to automatically assign it to multiple users.
Features and updates in this version
This version of the integration includes several updates and enhancements:
- The xMatters application is certified for use with ServiceNow Helsinki and ServiceNow Istanbul.
- All web services calls are now REST based. Events are injected via the Integration Builder and data sync calls use the xM API.
- Within ServiceNow, all operations happen asynchronously, improving performance by directly calling worker processes or by queuing events.
- The configuration pages and user interface for the xMatters application within ServiceNow have been redesigned to provide a better user experience.
- Instead of callbacks being passed in from ServiceNow, outbound integration webhooks are now configured in xMatters to allow for ease of use, improved customization, and faster troubleshooting.
Note: Our integration boffins have been hard at work experimenting with ways to extend the functionality and features offered in this integration. For more information, see the Extended functionality section.
Engage with xMatters
This version of the integration includes updates to the Engage with xMatters feature, which allows users with the x_xma_xmatters.xmatters_engage role to leverage xMatters to call in additional members from other teams to assist with an existing incident.
For example, imagine that a support team member has taken ownership of a ticket, but needs help from the database team to resolve part of the problem. Instead of assigning the ticket to someone else and losing the benefits of incident ownership, the support team member can use the Engage with xMatters feature to contact the on-call person in the database group. xMatters continues to update the work notes of the ServiceNow incident so the support team member can still receive real-time updates on whether someone else has started work on the incident and who that person is.
Alternately, the support team member could use the Engage with xMatters conference bridges to bring multiple groups together through xMatters hosted or external conference bridges to work on a solution together.
The Engage with xMatters features now also provides the ability for ServiceNow users to get help from or notify users of xMatters that don't exist in ServiceNow. In previous versions, this was only available via subscriptions on the Configuration Item List property. With this version, if there is a group or person that does not exist in ServiceNow, you can still find them using the Engage with xMatters feature and get them up to speed directly.
Install the xMatters application
To begin, you need to install the xMatters app in ServiceNow. The application includes all of the batch loading utilities, configuration pages, business rules, scripts, web services, and other components required for ServiceNow to communicate with xMatters.
To install the xMatters application:
- If you are installing the xMatters app into your ServiceNow for the first time, go to the ServiceNow store at store.servicenow.com, and search for "xMatters". When you find the app, click Get, and you will be prompted to enter your system credentials to add the app to ServiceNow.
- Log into ServiceNow as a system administrator, and navigate to System Applications > Applications.
- Click Downloads.
- Search for "xMatters", and then click Install (or Update):
ServiceNow API user
You will also need the user name and password for a ServiceNow API user to handle REST web service calls in ServiceNow. To successfully access the REST endpoint and execute the required integration requests, this user must have the x_xma_xmatters.xmatters_rest role that is added with the xMatters application. (For additional security, you should also select the Web service access only check box on the user's details page.)
Note: You should also assign the x_xma_xmatters.xmatters_engage role to this user so they can update the Engage with xMatters records.
For information about adding users and assigning roles in ServiceNow, refer to the ServiceNow documentation.
Configure xMatters On-Demand
You may find it easier to configure xMatters first because some of the configuration screens in ServiceNow require specific IDs or URLs for xMatters elements.
Download the communication plan
The communication plan (.zip file) attached to this article contains pre-configured integrations, forms, properties, and messages specifically designed for ServiceNow. Download the attached .zip file to a location on your local machine.
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.
If this role does not exist in your deployment already, you may need to ask Customer Support to create it for you. To successfully execute some of the tasks for this integration, the integration user requires some additional permissions in xMatters, as indicated in the following steps.
Note for trial: 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. For this integration, you will need to add the Group Supervisor, Person Supervisor, and Support User roles to the Integration User, but can otherwise 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 will affect how messages appear for recipients and how events will be displayed in the reports and Communication Center, you may want to identify the user as specific to ServiceNow; for example:
- First Name: ServiceNow
- Last Name: Integration
- User ID: servicenow
- Make a note of these details; you will need them when configuring other parts of the integration.
Import the communication plan
The next step is to import the ServiceNow communication plan.
To import the ServiceNow communication plan:
- In xMatters, click the Developer tab, and then click Import Plan.
- Click Browse, and then locate the following file from the extracted integration archive:
- Click Import Plan.
- Once the import is finished, the plan should be automatically enabled. If it isn't, click Plan Disabled to enable the plan.
After you have imported the communication plan, you need to set the authentication for the xMatters and ServiceNow endpoints. You will need the user name and password for your xMatters REST API user, and for your ServiceNow API user.
To configure the endpoints:
- On the communication plan, click the Integration Builder tab, and then click the Edit Endpoints button to display the endpoints for the integrations.
- Click the xMatters endpoint, update it with the credentials for the integration user you created above (or, if you are using a trial instance, to "Integration User"), and then click Save Changes.
- Click the ServiceNow endpoint to open its details, and then click the Authentication drop-down list and select Basic.
- Enter the credentials for the ServiceNow API user, and then select the Pre-emptive check box.
- Click Save Changes, and then close the Endpoints dialog box.
Accessing web service URLs
When configuring ServiceNow, you will need to specify the Web Service URL for each of the forms within the communication plan.
To get the web service URL for a specific form, click the Web Service Only drop-down list, and then select Access Web Service URL. Copy the highlighted URL at the top of the dialog box:
Some configuration fields require a UUID (Universal Unique Identifier) for a specific component or property in a communication plan. To retrieve the identifier for an element, look for the API icon in the xMatters user interface:
Clicking this button will display the identifier for the component in a dialog box; you can copy and paste the string to the appropriate location in ServiceNow.
As an example, the following instructions describe how to retrieve the UUID for a specific response choice; the process is similar for any identifier you want to determine.
To retrieve the identifier for a response choice:
- In xMatters, open the ServiceNow communication plan.
- On the Incident Alerts form, click Edit > Responses.
- Click the drop-down list in the Options column for the Accept response, and then click the API icon:
To configure ServiceNow to integrate with xMatters, you need to specify the assignment, synchronization, web services, and other settings on the configuration forms that are installed with the xMatters application, as described in the following sections. You can also seed your users and groups into xMatters using the data sync feature.
Note: Only users with the ServiceNow x_xma_xmatters.xmatters_admin role (added by the xMatters application) can modify xMatters components within the ServiceNow interface.
Complete the xMatters Configuration pages
The xMatters application installs four configuration pages into ServiceNow:
- Common Configuration: Configures the connection, credentials, and logging level for the communication between xMatters and ServiceNow.
- Incident Notifications: Enables or disables the incident notification features, and configures when and how ServiceNow will send an incident to xMatters for notification.
- Engage with xMatters: Enables or disables the Engage with xMatters action in the ServiceNow user interface, and sets the connection parameters for the feature.
- Data Sync: Configures the user and group seeding, and the data synchronization between xMatters and ServiceNow.
You will need to update most of the settings on these pages with information specific to your xMatters deployment.
To access the configuration pages in ServiceNow:
- Log into ServiceNow as a user with the "admin" role, and open the Navigator.
- Locate and expand the Integration - xMatters entry in the All Applications list, and then click xMatters Configuration.
- Click the tabs at the top of the window to switch between pages.
Web Service URLs
The Incident Notifications and Engage with xMatters pages require you to enter the web service URLs for the forms included in the communication plan. For instructions on how to retrieve these URLs, see Accessing web service URLs, above.
Some fields require you to enter the identifier or UUID for a property or other element in xMatters. For instructions on how to retrieve these identifiers, see Determining identifiers, above.
Data Sync Supervisors
On the xMatters Configuration > Data Sync configuration page, the Supervisor field displays a list of supervisors available in xMatters. You can select a user name from the list or enter your own. In either case, the selected user MUST be in ServiceNow and must have the "x_xma_xmatters.xmatters" role.
If a selected supervisor does not exist as a user in ServiceNow, or does not have the "x_xma_xmatters.xmatters" role, the user and group data sync will not be completed properly.
Add Engage with xMatters records to a related list
You can use the Related Lists feature in ServiceNow to have any related Engage with xMatters records included on the incident details.
To set up a related list:
- Open an existing incident record, click the menu button, and then select Configure > Related Lists.
- If the current application is not global, you will see a read-only screen with several options for editing. Select the Edit this view in Global link.
- In the Available list, select xMatters Engage Records, and move it to the Selected list.
- Click Save.
The xMatters Engage Records tab at the bottom of the incident details screen will now display the related Engage with xMatters records for that incident.
Seed user and group information into xMatters
Once you have established the configuration settings for you integration, you can use the Batch Load features to seed xMatters with your ServiceNow users, groups, and configuration items.
The xMatters application includes a pre-configured role, x_xma_xmatters.xmatters. In previous versions of this integration, the "itil" role was required for all users you wanted to notify via xMatters; the x_xma_xmatters.xmatters role controls both the synchronization and whether a user can be notified.
Assign the x_xma_xmatters.xmatters role to any users or groups you want to synchronize into xMatters. Assigning this role to a group will automatically assign it to all users within a group, or you can add this role to an existing role to automatically assign it to multiple users.
Batch load vs. dynamic sync
There are some fundamental differences between batch data load and dynamic synchronization that you should consider when designing your integration between xMatters and ServiceNow.
- A dynamic sync is initiated by a business rule, and typically involves a single object, such as a user with a specific role.
- The process for a dynamic sync occurs in background worker processes while business rules run in the foreground.
- Batch loads deal with collections of objects, such as ALL users with a specific role, and run entirely in the background.
What this means is that if you add a role flagged for sync to 300 users, the integration will fire the business role 300 times - once for each affected user - and in turn will perform processing and REST requests to xMatters individually for each user. These business rules run independently from each other, and thus no economies of scale are possible. If the integration needs to determine if a specific user or group in ServiceNow is set as a person or group supervisor in xMatters, all of the logic, look-ups, and updates must be performed each time the business rule fires. The same is true for determining group memberships: even if all members are part of the same group, the integration needs to query the group membership from xMatters once for each time the business rule fires.
Also, the business rule itself must be run in the foreground, even though the REST calls and actual synchronization of data occurs in the background processes during a dynamic sync. This allows current values to be compared against previous values to determine if the sync is necessary.
Batch loads reduce much of this redundancy by performing fewer data lookup queries, and caching the results for re-use. By minimizing redundant network traffic (REST requests) and database look-ups, a batch of user updates can be run much more efficiently, and entirely in background processes.
NOTE: Running a batch load script is a resource-intense process that can significantly affect server performance. This feature processes every user and group in your ServiceNow instance to determine whether they should be synchronized to xMatters. It is recommended that you run the batch load process only when the integration is initially installed, and only during non-peak server times to minimize the server strain and processing time required to complete the synchronization.
Batch load users and groups
The batch data load processes all users, groups, and group members in ServiceNow and attempts to update them in xMatters. If the user or group does not exist in xMatters, it is added; if the user or group already exists in xMatters, it will be updated. A user or group that exists in xMatters but not in ServiceNow is not modified by the batch process; updates to these items are handled by the user and group synchronization process based on individual changes only after the initial data load is complete.
NOTE: To prevent groups from attempting to add users that do not yet exist in xMatters, always run Batch Load Users before Batch Load Groups.
To initiate a batch data load:
- In the ServiceNow Navigator, under the Integration - xMatters heading, click Batch Load Users.
- On the Batch Load Users page, click Load Users.
- When the process is complete, click Batch Load Groups.
- On the Batch Load Groups page, click Load Groups.
Batch load incident properties
You can populate the configuration_item_list property in the xMatters integration with the configuration items available in ServiceNow. This will allow users to subscribe to incidents that occur on a specific Configuration item. By default, this property is set to include only the value NONE; to use this property, you must seed it with values using the Batch Load Incident Properties script. This will retrieve the configuration items as defined by the "Configuration Item Property Query" in the Data Sync configuration page, and send them to the configuration_item_list property.
The code to populate a value in the configuration_item_list property is disabled when the xMatters integration is first installed because, once enabled, the integration validates the entries in all of the list properties, and rejects the event if a configuration item is sent that is not in the list. To enable this feature, open the xMattersConfig Script Include, and change line 46 from:
To initiate a batch load of configuration items:
- In the ServiceNow Navigator, under the Integration - xMatters heading, click Batch Load Incident Properties.
- On the Batch Load Incident Properties page, click Load Properties.
Notifying non-synchronized users
By default, the integration is configured so that ServiceNow only sends incidents to users who are synchronized with xMatters. If you want ServiceNow to be able to send incidents to xMatters users who are not part of the data sync, open the xMattersConfig Script Include, and change line 52 from:
How to use the integration
After you have completed the configuration steps and performed the initial batch data load, you can test notification delivery and response, and the synchronization between xMatters and ServiceNow.
The user and group synchronizations work in an identical way, but you should still validate each synchronization independently.
Synchronize a user
When you create, modify, or remove a user in ServiceNow, the system activates a business rule and adds, updates, or deletes the corresponding user in xMatters, along with their device details.
To test the user synchronization:
- In the ServiceNow Navigator, open User Administration > Users.
- On the Users page, click New.
- Enter the details for a new user on the User page, including first and last names, a user ID, and an email address that you can access (so you can use this user to test the notification portion of the integration in the following sections):
- Click Submit.
- In the Users list, locate the user you just added and click their name.
- On the User page, in the Roles area, click Edit.
- On the Edit Members page, in the Collection list, select x_xma_xmatters.xmatters and then click Add.
- As explained above, this role is required for all ServiceNow users that you want to be synchronized with or receive notifications from xMatters.
Now log in to your xMatters instance and navigate to the Users page. If the synchronization was correctly configured, it will have added a matching user to xMatters using the settings on the Data Sync configuration page, and the email address as their email device.
Synchronize a group
When you create, modify, or remove a group in ServiceNow, the system activates a business rule and adds, updates, or deletes the corresponding group in xMatters.
To test the group synchronization:
- In the ServiceNow Navigator, open User Administration > Groups.
- On the Groups page, click New.
- Enter the details for a new group on the groups page, and then click Submit.
- In the Groups list, locate the group you just added and click its name.
- On the Group page, in the Roles area, click Edit.
- On the Edit Members page, in the Collection list, select x_xma_xmatters.xmatters and then click Add.
- As explained above, this role is required for all ServiceNow groups that you want to be synchronized with xMatters.
Now log in to your xMatters instance and navigate to the Groups page. If the synchronization was correctly configured, a group with a matching name is created automatically in xMatters, with a default 24x7 schedule and an empty roster. To further test the synchronization, add the test user you created for the user synchronization to the new group in ServiceNow, and confirm that the matching user is added to the group in xMatters.
Trigger a notification
To test the incident notification portion of the integration, you can create an incident in ServiceNow and assign it to the user you created for the synchronization test.
To trigger a notification:
- In the ServiceNow Navigator, open Incident > Create New.
- On the Incident Details page, enter the details for a test incident with a Priority setting of "High" or "Critical".
- In the Assigned To field, enter the name of your test user.
- Click Submit to trigger the notification.
Engage with xMatters
You can test the Engage with xMatters feature using an existing incident.
To engage with xMatters:
- In the ServiceNow navigator, open Incident > Open.
- In the list of incidents, click an incident's number to open it.
- On the incident's details page, click Engage with xMatters.
- In the Engage with xMatters dialog box, enter additional details about the incident in the provided fields, and use the Recipients area to add the people or groups you want to notify.
- Click Submit.
Respond to a notification
When the notification for the test user arrives on your device, open the message to view its details. For example, the following illustrates how a ServiceNow notification via xMatters might appear in the xMatters mobile app:
You can respond to the message simply by tapping one of the response choices. Other devices use similar methods: in an email notification, you would click a link in the message body; for an SMS, you would send an SMS reply containing a response option (or even a single digit).
For a voice notification, you would press a button on your phone to indicate your choice. If the message included a conference bridge request, the message is read aloud via the text-to-speech feature, and you would be prompted to join the conference. For example:
This is a manual conference bridge notification from ServiceNow regarding INC0000054.
Message: The SAP system is throwing database errors.
Press 1 to join the conference, press 2 to ignore and stop notifying.
View response results
After you respond to the notification, you can see how the integration automatically updates the Activity section in the incident Notes:
View Engage with xMatters responses
To view responses to Engage with xMatters notifications, use the ServiceNow Navigator to open Integration - xMatters > Miscellaneous > Engage with xMatters Records. Click the number of the record you want to view.
The unofficial/official Integration Research and Development wing of xMatters (those clever elves over at the xMatters Labs) devised a couple of cool ways to extend and enhance this integration:
- Inform with xMatters - An "add-on" for ad-hoc FYI type notifications from ServiceNow.
- CI Support Groups - An "add-on" for including the upstream and downstream CI groups to the Engage with xMatters form.
Check out each of these enhancements at the links provided, and keep an eye out for future improvements, too! (Remember that these features are in-progress or experimental additions to this integration, and as such we can provide only limited support should you choose to implement them.)
The xMatters integration 3.7.12 release is now listed in the ServiceNow store with certified support for Instabul!
(I've updated the document to reflect this...)
Based on some customer feedback, I've added a section that identifies the ServiceNow roles that the xMatters integration adds, and clarified some of the situations where the roles are required or recommended.
Updated this article to include references to the new, experimental functionality on offer at the xMatters Labs.
Added a new section explaining how to add xMatters Engage Records to the incident details using the Related Lists feature in ServiceNow.
The latest and greatest version of the xMatters - ServiceNow integration is now available and certified for use with Jakarta!
Check it out here!