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
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.
Integration Version
Version 5.4 of the xMatters application within ServiceNow is certified with Kingston, London, Madrid, and New York.
Are you using the ServiceNow steps in Flow Designer?
Flow Designer - our drag-and-drop, visual workflow builder - includes steps to easily add ServiceNow to your incident management workflow. You can find help on using the ServiceNow steps in the xMatters On-Demand help. Just install the xMatters app in ServiceNow and create a ServiceNow API user, then you're ready to go.
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 xMatters API REST message for synchronization requests. ServiceNow REST messages are received by the inbound integrations on the communication plan, where the appropriate notification layout is determined based on the target device. xMatters API messages are received by the xMatters REST operations, and devices, users, or groups are added, updated, or deleted appropriately.
If you're more a visual person or really want to get into the details, we've put together some flow diagrams of how the pieces of the integration work together.
See The Resolve response and the "Incident Management Best Practice" plug-in for important information on using the Resolve response with new data policies in the plug-in.
ServiceNow Roles
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 ServiceNow API User, 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 automatically assigns 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 automatically assigns 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
Updates
Along with all of the fixes and updates from previous versions, this release (5.4) includes the following enhancements:
- Version 5.4.1 certified for the New York release of ServiceNow.
- Data sync will now properly remove synced groups from xMatters when the group is removed in ServiceNow.
- Updated the Engage with xMatters behavior to make sure corresponding events in xMatters are terminated when closing an Engage with xMatters record, and to address an issue that was causing some requests involving Mid-Server to run for a long time.
The 5.3 version of the integration included the following updates:
- Refined the data synchronization scripts to improve performance.
- Moved values from xMattersConfig script include into system properties. If you've customized this script include in the past, there are a few extra steps you'll need to follow as part of the upgrade process.
The 5.2 version of the integration included the following updates:
- Version 5.2.4 certified for the Madrid release of ServiceNow.
- Updated the search behavior to use AND instead of OR when looking for people or groups to target in the Engage with xMatters dialog box.
- Added a new setting in the Engage with xMatters configuration screen that lets you set the maximum number of results to return when searching for recipients to target.
- Addressed issues with dynamic sync functionality when upgrading from a customized 4.x version, incident custom queue load balancing, and errors when syncing groups from ServiceNow for the first time when the group already exists in xMatters.
The 5.1 version of the integration included the following updates:
- Certified for the London release of ServiceNow.
- The group data sync now preserves (instead of overwriting) any supervisors you've set up for a group in xMatters.
- Improvements to the xMatters configuration page in ServiceNow, including showing you if you've already entered a password and accepting xMatters hostnames with an extra backslash at the end. We also cleaned up some unused configuration settings.
The 5.0 version of the integration included the following updates and enhancements:
- Updated Data Sync components to avoid hitting Progress Worker Quota limits introduced in ServiceNow Jakarta.
- Added Initiator to the “Engage with xMatters” form.
- Added targeted recipient and ServiceNow initiator information to the event notification (requires the 5.0 communication plan).
This version also includes all the features and updated added in previous versions of the xMatters integration.
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.
To upgrade from a previous version:
If you're upgrading from a previous version of the integration, check out our instructions to guide you through the process.
User and group data load
You can use the Batch Load features to seed xMatters with your ServiceNow users, groups, and configuration items.
Once you've seeded xMatters with your users and groups, you can use dynamic data sync to keep xMatters in tune with ServiceNow. If you add supervisors to a group or user in xMatters, or give a user additional roles, these are preserved in future syncs.
Engage with xMatters
This integration includes 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. When the on-call person in the database group gets the alert from xMatters, they can see who sent them the Engage with xMatters request. In the meantime, 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. You can even add people to an on-going conference bridge for a ServiceNow incident.
The Engage with xMatters features also provides the ability for ServiceNow users to get help from or notify users of xMatters that don't exist in ServiceNow. If the group or person you're looking for doesn't exist in ServiceNow, you can still find them using the Engage with xMatters feature so you can get them up to speed directly.
The Resolve response and the "Incident Management Best Practice" plug-in
The Kingston release of ServiceNow introduced a new data policy, installed with the "Incident Management Best Practice" plug-in, that requires both the Resolution code and Resolution notes fields to be completed before the incident can be resolved or closed.
Currently, xMatters does not support completing both these fields when you select the Resolve response option. We're working on addressing this issue, but in the meantime, you can use one of the following workarounds:
- Remove the "Resolve" response from the Incident Notifications tab in the xMatters Configuration screen in Service Now,
OR - Deactivate the "Make close info mandatory when resolved or closed" data policy installed with the plug-in in ServiceNow (see the ServiceNow documentation for instructions).
Install the xMatters application
To begin, you need to install the free xMatters app in ServiceNow (if you're upgrading, check out our instructions). 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. You'll 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.
ServiceNow API user
You 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, 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
Now that you've done the basic configuration in ServiceNow, you can configure xMatters. After you configure xMatters and copy some specific IDs and URLs, you'll need to return to ServiceNow to finish the setup.
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.
The communication plan for version 5.0 hasn't changed, so you can also use it for v5.1.
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 more information.
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.
Import the communication plan
Next, import the ServiceNow communication plan attached to this article into xMatters.
To import the ServiceNow communication plan:
- In xMatters, click the Developer tab, and then click Import Plan.
- Click Choose File, and then locate the plan you downloaded from this article.
- 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.
- 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 for the plan, select Forms.
- The forms should be automatically deployed. If they aren't, click Not Deployed beside each form and select Enable for Web Service.
- For the Incident Alerts form, click the Web Service drop-down list and select Sender Permissions.
- Add the integration user, and then click Save Changes.
- Repeat steps 7-8 for the Engage with xMatters and Conference Bridge forms.
Configure the endpoint
The communication plan uses an endpoint with the ServiceNow authentication type. After you import the communication plan, you need to set the URL and authentication credentials (the user name and password for your ServiceNow API user) for the endpoint.
To configure the endpoint:
- In the Integration Builder, click Edit Endpoints.
- Click the ServiceNow endpoint to open its details.
- Update the Base URL to that of your ServiceNow system.
- Enter the credentials for the ServiceNow API user.
- Click Test Authentication to send a request using the username and password to the ServiceNow instance you entered in the Base URL field.
- This request checks that the xMatters App is installed in the ServiceNow instance. If the page displays a message that the authentication failed, check the credentials and permissions of the ServiceNow API user in ServiceNow, the Base URL you entered, and that the app is installed in that instance.
- Click Save Changes, and then close the Endpoints dialog box.
ServiceNow steps in Flow Designer require the ServiceNow authentication type so we recommend leaving the authentication type as is if you want to use ServiceNow steps in your flows. To change the authentication type, you need to create a new endpoint to replace the existing one. The easiest way to do this is to delete the existing endpoint and create a new endpoint using the same name before any steps in Flow Designer are configured to use the endpoint.
Configure inbound integrations
You need to update each of the inbound integrations to use basic authentication, and retrieve the URLs to configure the app in ServiceNow.
To configure an inbound integration and retrieve its URL:
- Navigate to the Integration Builder tab and expand the list of inbound integrations.
- Click the name of an integration to view its details.
- In the Select authentication method step, select Basic from the list.
- Click Update Inbound Integration.
- Scroll down to the bottom of the page, and click Copy beside the field:
Determine identifiers
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 displays the identifier for the component in a dialog box. You can then 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.
- Beside the Accept response, click the API icon:
Configure ServiceNow
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 sends an incident to xMatters for notification.
- Engage with xMatters: Enables or disables the Engage with xMatters action in the ServiceNow user interface, sets the connection parameters for the feature, and sets the maximum number of results to return when searching for people or groups to target.
- Data Sync: Configures the user and group seeding, and the data synchronization between xMatters and ServiceNow.
You 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.
Note: After you save your settings on the Common Configuration tab, the password fields turn into buttons, indicating there is a password entered for the user. Click the password button to update the saved password (for example, if you changed the integration user's password in xMatters).
Integration URLs
The Incident Notifications and Engage with xMatters pages require you to enter the URLs for the inbound integrations included in the communication plan. For instructions on how to retrieve these URLs, see Configure inbound integrations, above.
UUIDs
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 Determine 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 complete 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 now displays the related Engage with xMatters records for that incident.
Seed user, group and incident property information into xMatters
Once you've established the configuration settings for your 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. Assign this role to any users or groups you want to synchronize into xMatters. Assigning this role to a group automatically assigns it to all users within the group, or you can add this role to an existing role to automatically assign it to multiple users.
In previous versions of this integration, the "itil" role was required for all users you wanted to notify via xMatters; now the x_xma_xmatters.xmatters role controls both the synchronization and whether a user can be notified.
Changes to default shift name
Since this version of the integration was released, we changed the name given to the default shift created for every new group in xMatters. This requires a minor code change to the configuration script.
NOTE: If you are upgrading an existing ServiceNow installation, check out the knowledge base article here for more information and suggested workarounds.
If you're installing a new version of the integration:
- In ServiceNow, navigate to Advanced System Properties under Integration – xMatters.
- Change Group - Shift Name from '24x7' to 'Default Shift'.
- Save your changes.
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 rule 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.
How ServiceNow Supervisors and Group Managers are synced
ServiceNow supervisors are synced to xMatters with the Person Supervisor role, if they don't already have it.
For a user's supervisors, the process is additive – if a user has a supervisor in xMatters that they don't have in ServiceNow, when the batch data load or synchronization happens, the xMatters supervisor remains in place (in addition to any supervisor included in the sync from ServiceNow).
ServiceNow group managers are synced to xMatters with the Group Supervisor role, if they don't already have it.
You can choose to sync group managers from ServiceNow even if they don't have the xMatters sync role (x_xma_xmatter.xmatters). To use this feature, select the Always Sync Group Managers option on the xMatters Configuration – Data Sync page.
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 is 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 ServiceNow, 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 allows 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 retrieves the configuration items as defined by the "Configuration Item Property Query" in the Data Sync configuration page, and sends them to the configuration_item_list property in xMatters.
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:
- In ServiceNow, navigate to Advanced System Properties under Integration – xMatters.
- Select the box under Incident - Send Configuration Item List.
- Save your changes.
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. However, you can set it up to send incidents to xMatters users who are not part of the data sync.
To enable this:
- In ServiceNow, navigate to Advanced System Properties under Integration – xMatters.
- Select the box under Incident - Send to Synced Recipients Only.
- Save your changes.
How to use the integration
After you complete the configuration steps and perform the initial batch data load, you can test notification delivery and response, and the synchronization between xMatters and ServiceNow.
Validate synchronization
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.
- Click Save.
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.
- Click Save.
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 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 or group you created for the synchronization test. If you assign it to the user, only that individual is notified; if you assign it to a group, xMatters works its way through the group escalation until someone responds with "Accept". When that happens, the Assigned to field in ServiceNow is updated to the user that responded.
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.
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.
View response results
After you respond to the notification, you can see how the integration automatically updates the Activity section in the incident Notes:
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.
- For groups, this also searches the group description. Multiple search terms are treated as an AND (for example, searching for "database" and "admins" will return the group Database Admins but not Network Admins).
- Click Submit.
- To add a new user or group, simply add them to the recipients and click Submit. This adds them to the on-going Conference Bridge associated with the incident ID.
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.
Troubleshooting
If you are encountering difficulties with the integration and want to view more detailed information, select the Enable Debugging check box on the xMatters Common Configuration page in ServiceNow. This increases the level of detail contained in the log messages for the integration.
To access the xMatters logs in ServiceNow, look in the Integration - xMatters menu, under Miscellaneous > xMatters Logs.
You can also find more information in the Activity Stream for each inbound and outbound integration: while on the Integration Builder tab, expand the inbound or outbound section, click the gear icon beside an 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.
Data sync troubleshooting
One possible cause of data sync errors is a custom field in xMatters that's been set to mandatory. To work around this, you need to either:
• populate that field with something in ServiceNow so it is included in the data sync, or
• update the custom field in xMatters so it isn't mandatory.
Extended functionality
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:
- ServiceNow Major Incident - Add ServiceNow Major Incident Management into the xMatters notification process.
- ServiceNow Inbound via IntegrationHub - Set up a trigger from any table and table entry in ServiceNow to create an event in xMatters.
- Problem Management with Engage - Extend the Engage functionality to the Problem Management module in Service Now.
- Post to Chat - Create a room in a chat application from the Engage with xMatters form.
- ServiceNow Event Log - Log all xMatters event data (such as event and delivery statuses) to a table in ServiceNow
- 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.)
Upgrading your integration
If you already have a working xMatters - ServiceNow integration, use the following steps to upgrade your instance. (If you are installing the integration for the first time, or creating a new integration, head up to the Install the xMatters application section).
Upgrading a standard (out-of-box) integration
Notes before you upgrade:
- If you're upgrading from integration version 3.4 (or older), you may find it easier to disable your current integration and install this version as a fresh installation.
- If you're upgrading from integration version 3.5, disable the data sync feature before beginning the upgrade process described below.
- If you're upgrading an integration that was originally installed using an update set, there are some extra steps you need to do after you upgrade to continue to insert Engage with xMatters records.
To upgrade your integration:
- Download the latest communication plan (attached to this article), and import it into your xMatters instance.
- Make sure your REST user has access permission to the plan, and sender permissions on the form.
- Open the Integration Builder tab in the imported plan, and set each of the inbound integrations to use Basic Authentication.
- Copy the URL for each inbound integration to a safe place, such as a text file.
- Copy the UUID for each of the response choices on the form to the same text file.
- Log in to ServiceNow and disable the Incident and Engage with xMatters features for your existing integration.
- Update the xMatters application to the latest version from the Applications listing screen in ServiceNow.
- If you installed your integration using an update set, make sure you reach out to the Customer Support team.
- Update the configuration pages with the inbound integration URLs and response UUIDs from your text file.
- Re-enable the Incident and Engage with xMatters features.
After you've upgraded your integration, you can make any changes to the configuration of your xMatters app in ServiceNow.
Upgrading a customized integration
If you have any customizations (from working with an xMatters consultant or ones you've made yourself), we strongly recommend attempting the upgrade in a non-production or staging environment first. That way you can run the necessary tests to ensure that integration functionality won't be affected.
If you encounter any problems or want to get some help before attempting your upgrade, please contact xMatters Customer Support and we can help come up with a migration plan.
Upgrading a customized integration prior to version 5.3 to the latest version
In version 5.3, we moved values from the xMattersConfig script include into a system properties. To upgrade from a version earlier than 5.3 to the latest, you need to update the system properties to match what is in your customized script include file.
- Backup your xMattersConfig Script Include. You can find this under the Integration – xMatters entry in the All Applications list, in the Script Includes section.
- Update your integration, accepting the changes in the latest version.
- Compare the backup of your original xMattersConfig file with the values in Advanced System Properties under Integration – xMatters, using the table below, and update the system properties, if needed, to match the values your customized integration expects.
| Advanced System Property | xMattersConfig Variable |
| Incident - Inactive States | INCIDENT.INACTIVE_STATES |
| Incident - Critical Priority | INCIDENT.CRITICAL_PRIORITY |
| Incident - Event Queue Suffix | INCIDENT.EVENT_QUEUE_BASE |
| Incident - Assignment Trigger | INCIDENT.TRIGGER_RULES.ASSIGNMENT |
| Incident - Priority Upgrade Trigger | INCIDENT.TRIGGER_RULES.PRIORITY_UPGRADE |
| Incident - SLA Alert Trigger | INCIDENT.TRIGGER_RULES.SLA_ALERT |
| Incident - Reopened Trigger | INCIDENT.TRIGGER_RULES.REOPENED |
| Incident - Delete Trigger | INCIDENT.TRIGGER_RULES.DELETE |
| Incident - Send Configuration Item List | INCIDENT.SEND_CONFIGURATION_ITEM_LIST |
| Incident - Suppress Events when Assigning to Self | INCIDENT.SUPPRESS_ASSIGN_SELF |
| Incident - Suppress Events with Empty Recipients | INCIDENT.SUPPRESS_NO_RECIPIENT |
| Incident - Send to Synced Recipients Only | INCIDENT.SEND_TO_SYNCED_ONLY |
| Event - High Priority | PRIORITY.HIGH |
| Event - Medium Priority | PRIORITY.MEDIUM |
| Event - Low Priority | PRIORITY.LOW |
| Event - Maximum Attempts | EVENTS.MAX_ATTEMPTS |
| Event - Maximum Field Length | EVENTS.MAX_FIELD_LENGTH |
| Group - Observed By All | OBSERVEDBYALL |
| Group - Shift Name | SHIFTNAME |
| User - Username Field | USERNAMEFIELD |
| Data Sync - Max User Processes (LEGACY - DO NOT USE) | MAX_USER_PROCESSES |
| Data Sync - Max Calls per Process | MAX_CALLS_PER_PROCESS |
| Data Sync - Calls per User Synced | CALLS_PER_USER |
| Data Sync - Calls per User Deleted | CALLS_PER_USER_DELETE |
| Data Sync - Calls per Group Synced | CALLS_PER_GROUP |
| Data Sync - Calls per Group Member Deleted | CALLS_PER_MEMBER_DELETE |
| Data Sync - Use Progress Workers (LEGACY - DO NOT USE) | USE_PROGRESS_WORKERS |
| Data Sync - Number of Queues | NUM_DATA_SYNC_QUEUES |
| REST Log Level - Normal Mode | REST_LOGLEVEL |
| REST Log Level - Debug Mode | REST_LOGLEVEL |
If there are values in your customized xMattersConfig Script Include that are not in the Advanced System Properties or the new xMattersConfig Script Include, we recommend:
- moving those values into another Script Include (you'll need to update any references to them in other Script Includes).
- not adding them back into the xMattersConfig Script so this file can be updated in future without you having to worry about merging your customizations.
Upgrade to the latest version of the xMatters app
There's been some changes to how our app is listed with ServiceNow. This means that ServiceNow needs to enable entitlement to the app in production environments, which also means an extra step for you if you want to upgrade from a previous version.
See the section on installing the app for the first time for more information on how to install the latest version of the app.
Previous updates
See our current features and updates list for new additions in v5 of the integration. Here's what was introduced in v4:
The 4.2 version of this integration includes the following fixes and enhancements:
- Implemented the new Event Comments trigger, which allows the integration to update the ServiceNow ticket with comments added to the event in xMatters (requires the 4.2 communication plan).
- Added support for the ServiceNow Compact User Interface.
- Updated the group data sync so any supervisors you've set up for a group in xMatters are preserved in future data syncs.
- Addressed an issue where a new incident was created even if the original incident was deleted before the outbound integrations ran.
- Cleaned up some console errors that were appearing in the Engage with xMatters dialog.
- Updated the response actions on the Engage with xMatters "Acknowledge" response and the Conference Bridge "Join" response so your second line of on-call users aren't notified if the first line responds with either of these options.
The 4.1 version of this integration includes the following fixes and enhancements:
- The data sync feature has been updated to address a minor flaw that could potentially cause the user sync to stop processing if it encountered an error.
- Addressed an issue where dynamically syncing a ServiceNow group with multiple inherited roles would not sync those roles to added users.
The 4.0 version of the integration includes several updates and enhancements:
- The xMatters application is now certified for use with ServiceNow Jakarta (in addition to Helsinki and Istanbul).
- The data sync feature has been updated to preserve roles for existing users. When initiating a sync, the process compares a user’s existing roles in xMatters, and will add any new roles assigned in ServiceNow. (Previously, the sync process would replace a user’s existing roles with whatever roles were indicated in ServiceNow.)
- The configuration pages for the xMatters application now target the inbound integrations on the communication plan, rather than the forms. This enables access to enhanced authentication and more customization options in the Integration Builder.
- Logging of xMatters events within ServiceNow has been improved, and a new setting on the Common Configuration page allows you to turn debugging-level logging on or off.
- The Engage with xMatters feature now allows you to add users to conference bridges already in progress for the related incident (in addition to creating new hosted or external conference bridges).
- You can now choose to sync group managers from ServiceNow even if they do not have the xMatters sync role (x_xma_xmatter.xmatters). To use this feature, select the Always Sync Group Managers option on the xMatters Configuration - Data Sync page.
- Some minor issues with the data sync process have been addressed, leading to performance and reliability enhancements.
This version also includes all of the features available in the previous version of the xMatters integration:
- 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 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.
How it works: the nitty gritty
If you thrive on detail, we've put together a few diagrams to show you how the various pieces of the integration work together with the nuts and bolts of ServiceNow.
Incident flow
Engage with xMatters flow
Data sync flow
22 Comments