ServiceNow 5.x

1. Go to the Triggers tab in the palette, expand the App Triggers section, and drag the trigger onto the canvas.
2. Double-click the trigger (or click the pencil icon).
3. Set the authentication method (we recommend Basic Authentication or API Key) and then copy the Trigger URL — you'll use this URL to set up the webhook in ServiceNow by configuring it to the 'Incident Notification' page or the 'Engage with xMatters' page on the xMatters app for ServiceNow.
   • By default, the workflow notifies the user or group assigned to the ServiceNow incident.



4. Click the Flood Control tab to edit the trigger's default flood control settings. For more information about these settings, see Trigger Flood Control.
5. Click Done.
6. On the flow canvas, connect the steps you want to run when xMatters receives a request to that URL.

You're now ready to configure ServiceNow to target the trigger.

To begin, install the free xMatters app in ServiceNow (if you're upgrading, see our upgrade instructions). Make sure your app is version 5.5 or later.

1. Go to the ServiceNow store at store.servicenow.com, and search for "xMatters".
2. When you find the app, click Get. You'll be prompted to enter your system credentials to add the app to ServiceNow.
3. Log into ServiceNow as a system administrator, and navigate to System Applications > Applications.
4. Click Downloads.
5. Search for "xMatters", and then click Install.

To configure the ServiceNow endpoint in xMatters, you need the username and password for a ServiceNow API user to handle REST requests from xMatters to ServiceNow. To access the REST endpoint and make the required integration requests, this user must have both the x_xma_xmatters.xmatters_rest and itil roles (added with the xMatters application). For additional security, select the 'Web service access only' check box on the user's details page.

For information about adding users and assigning roles in ServiceNow, refer to the ServiceNow documentation.

The xMatters app installs roles into ServiceNow that control who can use or make changes to its components and that manage the communications between ServiceNow and xMatters.

• x_xma_xmatters.xmatters_admin: Only users with this role can modify xMatters components within the ServiceNow interface.
• x_xma_xmatters.xmatters_rest: You must have a ServiceNow API user with this role to successfully access the REST endpoint and execute the required integration requests.
• x_xma_xmatters.xmatters_engage: Users with this role can use the Engage with xMatters feature.
• x_xma_xmatters.xmatters: Assign this role to any users or groups you want synchronized into xMatters.
• itil: Users with this role can create and modify incidents, allowing them to use the Create Incident, Update Incident, and Add Comment ServiceNow steps in the ServiceNow (Flow Designer) workflow.

To assign a role to multiple users at once, you can:

• assign the role to a group — any users in that group inherit the role.
• assign the role to an existing role — any users assigned the existing role inherit the xMatters role.

The trigger requires a user who can authenticate REST requests from ServiceNow to xMatters when working with alerts. The necessary permissions are provided by the 'REST Web Service User' role in xMatters. See Create an integration user for more information on creating an integration user.

Keep the user ID and password of this user handy. You'll need them when configuring other parts of the integration.

The workflow this trigger is configured for uses an endpoint with the ServiceNow authentication type. Set the endpoint's URL and authentication credentials (the username and password for your ServiceNow API user).

To configure the endpoint:

1. On the workflow page in xMatters, go to the Flow Designer tab and select one of the flows to open Flow Designer.
2. Click Components from the top menu then select Endpoints.
3. In the Endpoints dialog, select the ServiceNow endpoint to view its details.
4. Update the Base URL to that of your ServiceNow system.
5. Enter the credentials for the ServiceNow API user.
6. Click Test Authentication to send a request using the username and password to the ServiceNow instance you entered in the Base URL field.
   • If the page displays a message that the authentication failed, check the Base URL you entered is correct, then check the credentials match the ServiceNow API user and that the user has the x_xma_xmatters.xmatters_rest role.
7. Click Save, and then close the Endpoints dialog.

1. Log into ServiceNow as a user with the 'admin' role, and open the Navigator.
   • Only users with the ServiceNow x_xma_xmatters.xmatters_admin role (added by the xMatters application) can modify xMatters components within the ServiceNow interface.
2. Locate and expand the Integration – xMatters entry in the All Applications list, and then click xMatters Configuration.
3. Click the tabs at the top of the window to switch between pages.
   • For an existing integration, we recommend doing a hard refresh before configuring settings (for example, CTRL+F5 on Windows or CMD+SHIFT+R on Mac) to make sure you have the latest and greatest version of the page.

• xMatters Hostname: The hostname of your xMatters deployment (for example, https://your-company.na1.xmatters.com). Make sure that the hostname doesn't end with '/'.
• xMatters REST API User: The username of the integration user used to authenticate requests to xMatters.
• xMatters REST API Password: The password of the integration user.
• ServiceNow API User: The ServiceNow API user you created to authenticate requests from xMatters to ServiceNow.
• ServiceNow API Password: The password of the ServiceNow API user.
• Enable MID Server and MID Server: Sets whether the integration should use a MID server when making requests to xMatters and the name of the MID server to use. See the ServiceNow documentation for information on using MID servers.
• Enable Debugging: Sets whether DEBUG messages are included in the xMatters log in ServiceNow. See the ServiceNow documentation for more information on ServiceNow logs.

After you save your settings, 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).

• Enable Incident Notifications: Turns on incident notifications.
• Incident Alerts Integration URL: The trigger URL for the workflow's Incident Alerts integration.
• Response Options for Users: Leave blank as this option is not used by this workflow.
• Response Options for Groups: Leave blank as this option is not used by this workflow.
• Priority: The priority of incidents that you want to send to xMatters.
• Language Suffix: The language of incident properties sent to xMatters. This value is appended to property names when the integration performs certain actions.
• Resolution: Use Resolution Code and Resolution Notes to set the values used for the resolution information when a recipient responds with Resolve. This is required to resolve or close an incident if the resolution data policy installed with the Incident Management Best Practices is enabled. If the policy is enabled, the resolution code cannot be None.
• Event Termination Settings: Select the Terminate Events by Form check box to only terminate alerts created by the xMatters workflow form specified in the Form Name field when a termination event happens (for example, when the incident is closed or the priority changes).

• Enable Engage with xMatters: Enables the Engage with xMatters feature (users need to be assigned the x_xma_xmatters.xmatters_engage role to be able to use the feature).
• Maximum number of suggestions in recipients list: The maximum number of suggestions the Engage with xMatters dialog displays when searching for recipients.
• Engage with xMatters Integration URL: The trigger URL for the workflow's Engage with xMatters integration.
• Conference Bridge Integration URL: The trigger URL for the workflow's Engage with xMatters integration (enter the same URL as the 'Engage with xMatters integration URL' field).
• External Conference Bridges: The names of external conference bridges to make available in the Engage with xMatters dialog; leave blank to use xMatters-hosted conference bridges. See the xMatters online help for more information on conference bridges.

Before configuring the data sync settings, we recommend you review the information on syncing users, groups, and properties from ServiceNow to xMatters.

Properties

• Enable Dynamic Sync: Turns on dynamic syncing of users, groups, and properties from ServiceNow to xMatters.
• Check Instance URL: The data sync to xMatters will only be attempted if the ServiceNow instance URL matches the value entered in this field. Entering a URL into this field is optional.
• Site: The xMatters site to assign users and groups added via the data sync to.
• Supervisor: The user ID of the supervisor in xMatters you want users added via the data sync to be assigned to. If this is left blank, the user will not have a supervisor in xMatters until you manually add one.
• Always Sync Group Managers: Sync group managers even if they aren't assigned the x_xma_xmatters.xmatters role. See how ServiceNow Supervisors and Group Managers are synced.
• Time Zone: The time zone you want to set for users and groups when they're added to xMatters.
• Externally Own Data: When set, synchronized data can only be removed from xMatters by removing it from ServiceNow.
• Web Login Type: Whether the user logs into xMatters using their web login (native) or LDAP.
• Language: The language to set for users when they're added to xMatters.
• LDAP Domain: The LDAP domain to use if Web Login Type is set to LDAP.

People

• Role: The xMatters role to assign to people added to xMatters via the data sync. Use the xMatters web user interface to give the user additional roles.
• Phone Device: The xMatters device name to assign to a user's voice device.
• SMS Phone Device: The xMatters device name to assign to a user's SMS device.
• Email Device: The xMatters device name to assign to a user's email device.
• Phone Extension Identifier: The component of a phone number in ServiceNow that denotes an extension (for example, 'x' or 'ext'); this lets xMatters recognize phone extensions.

Groups

• Allow Duplicates: Enables the Allow Duplicates setting for a group added via the data sync; this setting determines whether a member can be added to the escalation timeline more than once.
• Group - Use Default Devices: Enables the Use Failsafe Devices setting for a group added via the data sync; this setting determines if xMatters should contact a group members failsafe (default) device if they don't have any devices with an active timeframe.
• Default Shift Name: The name of the shift the data sync adds users to. If you already have a default shift name, update this setting to match. Otherwise you can leave it as is to match the current Default Shift default in xMatters.

Incident Properties

• Configuration Item Identifier: The UUID of the configuration item list property in the ServiceNow workflow. To sync the values of this list from ServiceNow to xMatters, see Batch load incident properties.
• Configuration Item Query: The ServiceNow query of cmdb_ci records to send for the configuration item list property. See the ServiceNow documentation for more information on querying for cmdb_ci records.

1. Navigate to the Advanced System Properties screen under Integration - xMatters.
2. Find the Event - Use Event Legacy Payload Format setting and clear the check box.

If you want to upgrade an existing integration to use the new format, follow the upgrade instructions and make sure you update the integration scripts as outlined in this article.