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.

While version 5.5 of the ServiceNow integration brings a lot of usability enhancements and process improvements, the xMatters workflow only has minimal changes from the 5.0 version.

This means, if you're using the 5.0 version of the workflow, you can update it to take advantage of the 5.5 improvements, in particular the ability to configure which events are terminated, without having to replace the whole thing and laboriously copy over any customizations you've made.

Add the Language Suffix constant

1. Open the ServiceNow 5.0 workflow on the Workflows page and click on the Integration Builder tab.
2. Click Edit Constants and then click Add Constant.
3. Enter Language Suffix as the name (this is case-sensitive) and set the value to #en.
   • You can add an optional description if you'd like, maybe something like "This constant is used when the workflow looks up properties in xMatters, such as those used in finding events to terminate".
4. Click Save Changes.

Update the inbound integration scripts

There are a couple of changes to the inbound integration scripts to support the event termination logic and improved recipient handling to support both legacy and xMatters REST API formats.

1. On the Integration Builder tab, expand the inbound integrations and click the name of the inbound integration (for example, Incident Alerts).
2. Scroll to the bottom and click Save and Open Script Editor.
3. Make the script changes outline for the script:
   • Incident Alerts
   • Engage with xMatters and Conference Bridge
4. Click Save.

For your integration to use the updated event termination logic, you also need to configure the Event Termination settings on the Incident Notifications configuration page for the xMatters app in ServiceNow.

Incident Alert script changes

1. Find the line that reads (line 18 before any edits):

   util.terminateEvents({'sys_id': incidentId});

2. Replace it with:

   var eventProperties = {};
   eventProperties['sys_id#' + constants['Language Suffix']] = incidentId;
   util.terminateEvents(eventProperties, trigger.properties.incidentAlertFormName);

3. Find the line that reads (line 24 before any edits):
   

   recipientName = trigger.recipients[0].targetName;

4. Replace it with:

   var recipient = trigger.recipients[0];
    if (recipient.id) {
     recipientName = recipient.id;
    } else if (recipient.targetName) {
     recipientName = recipient.targetName;
    }

Engage with xMatters and Conference Bridge script changes

1. Find the line that reads (lines 8-11 before any edits):
   

   trigger.recipients.forEach(function(recipient) {
    targetRecipients.push(recipient.targetName);
    }
   );

2. Replace it with:

   trigger.recipients.forEach(function(recipient) {
    if (recipient.id) {
    targetRecipients.push(recipient.id);
    } else if (recipient.targetName) {
    targetRecipients.push(recipient.targetName);
    }
   });

Update the util shared library

Most of the library updates relate to the event termination enhancements. Change 2 also adds the logic to only return active groups in the Engage with xMatters dialog box.

There are two ways to update the library, depending on whether or not you've customized it.

• If you haven't customized it, you can copy-paste the entire contents of the attached text file into the library script editor.
• If you have customized it, you need to update it line-by-line.

If you're not sure — sorry, you should probably do the line-by-line update.

Update the library using the text file

1. Save and open the text file in a program such as Notepad.
2. On the Integration Builder tab, expand Shared libraries and click util.
3. Copy the contents of the text file and paste them into the script editor.
4. Click Save.

Update the library line-by-line

1. On the Integration Builder tab, expand Shared libraries and click util.
2. Make the replacements and additions outlined in the Script Changes section that follows.
3. Click Save.

Library script changes

The lines numbers in the original, uncustomized library are provide for each change. If you have customized your library, your line numbers might not match. Still, you might want to start from change 6 and work your way up.

Change 1 (line 15)

Find:

var getEvents = function(status, propertyNames, propertyValues) {

And replace it with:

var getEvents = function(status, propertyNames, propertyValues, formName) {
 var formClause = formName ? '&form=' + encodeURIComponent(formName) : '';

Change 2 (line 20)

Find:

'path': '/api/xm/1/events?status=' + status + '&propertyName=' + propertyNames.join(',') + '&propertyValue=' + propertyValues.join(','),

And replace it with:

'path': '/api/xm/1/events?status=' + status + '&propertyName=' + propertyNames.join(',') + '&propertyValue=' + propertyValues.join(',') + '&propertyValueOperator=EQUALS' + formClause,

Change 3 (addition below line 72)

Find the comment that begins "Terminate active events matching a set of properties".
In the comment, find:

 * @param {Object} properties a set of properties to search

Below it, add:

* @param {string} formName name of the form that created the events

This change isn't strictly necessary but...comment your code, right?

Change 4 (line 75)

Find:

exports.terminateEvents = function (properties) {

And replace it with:

exports.terminateEvents = function (properties, formName) {

Change 5 (line 91)

Find:

var activeEvents = getEvents(EVENT_STATUS.ACTIVE, propNames, propValues);

And replace it with:

var activeEvents = getEvents(EVENT_STATUS.ACTIVE, propNames, propValues, formName);

Change 6 (line 101)

Find:

var suspendedEvents = getEvents(EVENT_STATUS.SUSPENDED, propNames, propValues);

And replace it with:

var suspendedEvents = getEvents(EVENT_STATUS.SUSPENDED, propNames, propValues, formName);  

Download resources