xMatters for ServiceNow (Direct Integration)

This page contains instructions for maintaining existing integrations. If this your first time integrating xMatters with ServiceNow, we recommend that you start your integration with our built-in ServiceNow (Flow Designer) workflow instead. The workflow comes with more out-of-the-box features that integrate with Flow Designer, allowing you to seamlessly connect ServiceNow to your xMatters toolchain.

xMatters for ServiceNow is a direct, cloud-to-cloud integration, leveraging an xMatters workflow to become the voice and interface of an automation engine. When ServiceNow detects something that requires attention, xMatters places phone calls, sends emails, or notifies your mobile app.

The instructions cover the following topics:

 

Integration version — features and updates

Version 5.8 of the xMatters application within ServiceNow is certified with the following releases: Xanadu, Washington DC, Vancouver, Utah, Tokyo, San Diego, and Rome.

Are you using the ServiceNow steps in Flow Designer?

Flow Designer — our drag-and-drop, visual workflow builder — includes steps to add ServiceNow to your incident resolution workflow. You don't need to do any of the setup below if you simply want to use these in your flows; all you need to get started is an endpoint that targets your ServiceNow instance.

How the integration works

The integration consists of a workflow and the xMatters application within ServiceNow, which includes the following components:

  • Incident Alerts: Handles automatic notification about incidents and the sharing of incident information between ServiceNow to xMatters.
  • Engage with xMatters: enables ad hoc communications, including conference bridges, using xMatters.
  • User and data sync: synchronizes ServiceNow users, groups, and group members to xMatters.

For an overview of each component, expand the following sections. If you want a behind-the-scenes look at the different business rules, script includes, and web services each component uses to accomplish their tasks and how the pieces fit together, see our detailed how it works section.

For a live walk-through of how to set up the integration, attend one of our ServiceNow workshops – you can check for available workshops here.

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.

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.

If you have this data policy enabled, make sure you configure the Resolution section of the Incident Notifications configuration screen with the values you want to use for these fields when a recipient responds with Resolve.

Prepare ServiceNow

There are a couple of steps to get ServiceNow ready to integrate with xMatters — first and foremost, installing the xMatters app. However, you also need to create a user in ServiceNow to make requests, and assign the user specific roles installed with the application.

Configure xMatters

Now that you've completed the first part of the configuration in ServiceNow, it's time to configure xMatters. After you import the workflow into xMatters and copy some specific IDs and URLs, you'll return to ServiceNow to finish the setup (or you can have both applications open and switch between them as you go).

The basic steps to configure the workflow in xMatters are: create a user for the integration (this is optional but it makes it easier to identify which integrations are making requests and adding information to logs), download and import the workflow, configure the endpoint to point to your ServiceNow instance, and gather the inbound triggers URLs and response identifiers.

Configure ServiceNow

To configure ServiceNow to integrate with xMatters, you need to specify the assignment, synchronization, web services, and other settings on the configuration pages installed with the xMatters application. You can also use the data sync feature to seed your users and groups into xMatters.

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. See the following sections for more information on the settings in the Common Configuration, Incident Notifications, Engage with xMatters, and Data Sync tabs.

Send payloads to xMatters using the latest payload format

To maintain compatibility with existing integrations, the payload to trigger an alert is sent using a legacy format. For new installations, we recommend you change this to use the latest payload format. Besides being more future proof, it means you can also use the information in the xMatters REST API documentation to customize your payload if needed.

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.

Set what happens when an incident is canceled

When the ServiceNow incident's state changes to Canceled, the associated xMatters alert is terminated. You can removed Canceled from the list of states that terminated alerts if you want the xMatters alert to continue even if the incident is Canceled.

Activate the clone cleanup script

If you intend to clone your ServiceNow production environment, make sure the clone cleanup script for xMatters is set to Active before beginning the cloning operation.

The purpose of the clone cleanup script is to prevent the new clone instance from deleting user and group records in xMatters. If the clone cleanup script is not enabled when the clone is created, data sync activity on the clone can delete data from the xMatters production instance. To prevent this, the clone cleanup script removes user and password information so the clone cannot access the xMatters instance.

  1. Navigate to System Clone > Clone Definition > Cleanup Scripts.
  2. Click on the xMatters Clone script to open it.
  3. Select the Active check box.
    • If you can't select the check box, make sure you're in the xMatters application.
  4. Click Update.

The cleanup script runs automatically after the cloning process finishes. The ServiceNow admin can verify that the script ran correctly by checking the “x_xma_xmatters.xmatters.api.user” and password properties, and the “x_xma_xmatters.xmatters.reb.user” and password properties immediately after the clone is created; all of these values should be blank.

If you want the cloned environment to interact with a non-production xMatters instance, you need to configure the integration in the clone.

Sync user, group and incident property information with xMatters

After you've done the basic configuration for the integration, 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.

How it works

Here's an overview of the user, group and property sync from ServiceNow to xMatters:

  1. Assign the x_xma_xmatters.xmatters 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 all users with that existing role.
  2. Batch load users then groups (and incident properties, if needed).
  3. Enable Dynamic Sync on the Data Sync tab of the xMatters configuration pages to have any future changes synced to xMatters (either updates to synced objects or new users or groups assigned the x_xma_xmatters.xmatters role).

If you'd like a visual of how it works, we have diagrams of the batch load of users and groups, and for the dynamic data sync process.

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 they have the x_xma_xmatters.xmatters role. 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.

To prevent groups from attempting to include users that do not yet exist in xMatters, always run Batch Load Users before Batch 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 signal if a configuration item is sent that is not in the list.

Notify 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.

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 data synchronization

The user and group synchronizations work in an identical way, but you should still validate each synchronization independently.

Trigger and respond to notifications

To test the incident notification, 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 the 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.

Engage with xMatters

You can test the Engage with xMatters feature using an existing incident.

Troubleshooting

If you encounter 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, go to Integration - xMatters > 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 alert creation messages.

Data sync troubleshooting

One possible cause of data sync errors is a custom user property in xMatters that's been set to required. 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 property field in xMatters so it isn't required.

Extend your integration

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:

Check out each of these enhancements at the links provided, and keep an eye out for future improvements, too! The fine print: 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.

Architecture diagrams: how it works

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 workflow, 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 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.

Upgrade 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 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 the latest 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 (outlined in this article) that you need to do after you upgrade to continue to insert Engage with xMatters records.

To upgrade your integration:

  1. Download the latest workflow, and import it into your xMatters instance.
  2. Make sure your integration user has editor permission to the workflow, and sender permissions on the forms.
  3. Open the Integration Builder tab in the imported workflow, and set each of the inbound integrations to use Basic Authentication.
  4. Copy the URL for each inbound integration to a safe place, such as a text file.
  5. Copy the UUID for each of the response choices on the form to the same text file.
  6. Log in to ServiceNow and disable the Incident and Engage with xMatters features for your existing integration.
  7. 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 Support team.
  8. Update the configuration pages with the inbound integration URLs and response UUIDs from your text file.
  9. 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.

To make sure you have the latest and greatest version of the page, we recommend doing a hard refresh before configuring settings (for example, CTRL+F5 on Windows or CMD+SHIFT+R on Mac).

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.

After you upgrade, review the upgrade history in ServiceNow to see if any script updates were skipped. To review the skipped updates, click the script to view the upgrade details, and then click Resolve Conflicts to bring up the Resolve Conflicts form. From there, you can click the pop-out icon for the Script field and review the differences between the base script and your customizations, upgrading your custom script as needed.

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.

Features and updates in previous releases

See our current features and updates list for additions in the latest release.