ServiceNow

Flow Designer has a ServiceNow 5.x trigger and built-in ServiceNow steps to help you integrate ServiceNow into your alert management and incident response flows.

ServiceNow steps

The following steps are available:

  • Create Incident: automatically create a new incident in ServiceNow, populating it with information from the alert or any previous steps in the flow.
  • Update Incident: automatically update an incident as information about the event changes.
  • Add Comment: automatically add a comment to an incident, either as a public comment or an internal work note, including information from the alert or previous steps in the flow.
  • Send Integration Update: automatically update an existing incident or engage record in an xMatters integration with ServiceNow.
  • Update Record: automatically update any ServiceNow record type as information about the event changes.

In the example above, the flow creates a ServiceNow incident based on the response a recipient selects in the alert notification, and includes details from the source system. A Jira Cloud issue is created with additional information from the ServiceNow incident. A comment (internal) is added to the ServiceNow incident with the Jira Issue ID, then a message is posted to a Slack channel with information from the alert, the ServiceNow incident, and the Jira Cloud issue. Finally, the ServiceNow incident is updated with the name of the Slack channel and the thread the team used to collaborate in resolving the issue.

If you want to update an existing incident or engage record in an xMatters integration with ServiceNow, replace the Add Comment and Update Incident steps with the Send Integration Update step in the example.

  1. To add a ServiceNow step to your flow, go to the Apps panel in the palette, expand the ServiceNow steps and drag the step you want onto the canvas.
  2. Connect the step to the previous step in the flow. This lets you access the alert properties and outputs of previous steps when configuring this step's inputs.
  3. Double-click the step to edit it, and use the Setup tab to configure the inputs. You can use plain text and input variables (or both). See the sections below for detailed information on the inputs for each step, including which ones are required. Some things to keep in mind:
    • ServiceNow or your organization might have certain requirements for the fields that get populated by these steps.
    • Certain input values must match the case-sensitive options for a setting (for example, myname instead of MyName). If they don't, ServiceNow won't use them.
    • For other settings, the ServiceNow API accepts values the user interface won't display, so the field appears blank.
  4. On the Endpoint tab, configure the step to point to your ServiceNow instance.
    • You can select a pre-existing endpoint that uses the ServiceNow authentication type or create a new endpoint, setting the authentication type to ServiceNow and adding the URL to your ServiceNow system..

Create Incident

Use the Create Incident step to automatically create a new incident in ServiceNow. Map outputs from previous steps to the inputs; at runtime, the values in the inputs are used to fill in the incident record.

Inputs

Inputs with an asterisk* are required.

Label

API mapping

Description

Short Description*

short_description

A short description of the incident. You could create this using a mixture of text and mapped inputs.

Example: Map this to a summary property from the alert.

Description

description

A detailed explanation of the issue.

Example: Fill this input with a combination of plain text, a detailed description variable, and alert ID.

Caller

caller_id

The person who reported the issue. This can be the user ID, full user name or email address from ServiceNow.

Impact

impact

The level of impact on the business (for example, 1 or 1 - High).

Example: Use a switch step before this one, where a "Severity=Critical" path connects to a Create Incident step with a 1 - High Impact, while a "Severity=Medium" path connects to a step with a 2 - Medium Impact.

Urgency

urgency

Urgency to address the issue (for example, 2 or 2 - Medium).

Assignment group

assignment_group

The group in ServiceNow to assign the incident to. This can be the group ID or name from ServiceNow.

Assigned To

assigned_to

The user in ServiceNow to assign the incident to. This can be the user ID, full user name or email address from ServiceNow.

Category

category

The category to apply to the incident (for example, Hardware).

Subcategory

subcategory

The subcategory to apply to the incident (for example, Phone).

Business Service

business_service

The business service affected by the issue (for example, Public Website).

Configuration Item

cmdb_ci

The configuration item affected by the issue.

Contact Type

contact_type

The type of contact from the caller (for example, Email).

State

incident_state

The state to apply to the incident.

Outputs

These outputs are available as inputs to steps further along the flow.

Label

API mapping

Description

System Id

result.sys_id

The system ID assigned to the incident by ServiceNow.

Incident Number

result.number

The incident number assigned to the incident by ServiceNow. This appears as the incident number on the ServiceNow Record.

Example: Use this in the channel name in a Create Chat step further downstream.

Priority

result.priority

The priority assigned by ServiceNow.

Example: Use a switch step after this step to route the flow down different paths based on the priority.

Update Incident

Use the Update Incident step to automatically update the details of an existing ServiceNow incident. Map outputs from previous steps to the inputs; at runtime, the values in the inputs are used to determine the incident to update and update the record.

Inputs

Inputs with an asterisk* are required, and any fields you leave blank are not updated.

Label

API mapping

Description

System Id*

sys_id

The ID of the incident you want to update.

Short Description

short_description

A short description of the incident.

Description

description

A detailed explanation of the issue.

Impact

impact

The level of impact on the business (for example, 1 or 1 - High).

Urgency

urgency

Urgency to address the issue (for example, 2 or 2 - Medium).

Assignment group

assignment_group

The group in ServiceNow to assign the incident to. This can be the group ID or name from ServiceNow.

Assigned To

assigned_to

The user in ServiceNow to assign the incident to. This can be the user ID, full user name or email address from ServiceNow.

State

incident_state

The state to apply to the incident. When resolving an incident in ServiceNow, this parameter is required and must be set to 6 or 7.

Comments

comments

Add comments that are visible to customers. You can create the comment using plain text, mapped inputs, or both.

Work Notes

work_notes

Add comments that are only visible to internal users. You can create the comment using plain text, mapped inputs, or both.

Category

category

The category to apply to the incident (for example, Hardware).

Subcategory

subcategory

The subcategory to apply to the incident (for example, Phone).

Business Service

business_service

The business service affected by the issue (for example, Public Website).

Configuration Item

cmdb_ci

The configuration item affected by the issue.

Contact Type

contact_type

The type of contact from the caller (for example, Email).

Caller

caller_id

The person who reported the issue. This can be the user ID, full user name or email address from ServiceNow.

Resolved Code

close_code

Resolved Code (for example, Closed/Resolved by Caller). This parameter is required when resolving an incident in ServiceNow.

Resolution Notes

close_notes

Additional notes regarding the incident resolution. This parameter is required when resolving an incident in ServiceNow.

Resolved By

resolved_by

User who closed the incident. This can be the user ID, full user name or email address from ServiceNow.

Resolved At

resolved_at

Date and time when the incident is closed (must be in YYYY-MM-DD hh:mm:ss format).

On Hold Reason

hold_reason

Reason the issue is being moved to an On Hold state (for example, Awaiting Vendor).

Outputs

This step has no outputs.

Add Comment

Use the Add Comment step to automatically add a comment to a record in ServiceNow, either as an public comment or an internal work note. Map outputs from previous steps to the inputs; at runtime, the values in the inputs are used to determine the incident to update and the comment to add.

Inputs

Inputs with an asterisk* are required.

Label

API mapping

Description

Table*

The table of the ServiceNow record to add the comment to. Defaults to 'incident'.

Unique Record ID*

sys_id

The record the comment is added to.

Internal*

internal

Determines whether the comment is a work note that can only be viewed internally (true) or a public comment viewable by customers (false).

Comment*

comments | work_notes

 The text of the comment to add. You can create the comment using plain text, mapped inputs, or both.

Outputs

These outputs are available as inputs to steps further along the flow.

Label

API mapping

Description

Comment Added

 If the output returns the value 'true', the comment was successfully added. If the comment was not added, the output returns the value 'false', and the step will not fail.

Send Integration Update

Use the Send Integration Update step to automatically update an incident or engage record in an existing xMatters integration with ServiceNow and send alerts about these updates back to ServiceNow.

Map outputs from previous steps to the inputs; at runtime, the values in the inputs are used to determine the incident or engage record to update and the type of update to make.

This step is for users with existing xMatters integrations with ServiceNow that want to utilize Flow Designer in their incident management process. 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.

Inputs

Inputs with an asterisk* are required.

Label

API mapping

Description

Entity Type*

Type of entity to update. Available options are: incident, engage.

Update Type*

mode

Type of update to make. Available options are: eventCreation, deliveryStatus, response, status, comment.

Record ID*

eventProperties.sys_id

Unique record ID of the ServiceNow incident.

Engage Task ID

eventProperties.task_sys_id

Unique task ID of the ServiceNow engage record.

Alert ID*

eventIdentifier

Unique ID of the xMatters alert.

Alert Status

status

Status of the alert in xMatters. For example, Open, In Progress, Mitigated, Resolved, Rejected.

User First Name

author.firstName

First name of the xMatters user that left a comment.

User Last Name

author.lastName

Last name of the xMatters user that left a comment.

Recipient Target Name*

author.targetName | recipient

 Target name of the xMatters recipient that was notified.

Notification Delivery Status

deliveryStatus

Delivery status of the notification. For example, Delivered, Failed, Unchanged.

Device Name

device

Device name the xMatters user responded from. For example, "Work Email" or "SMS Phone".

Response

response

Notification response option selected by the recipient.

Comment

comment | annotation

 User-provided comment included with the notification response.

Outputs

This step has no outputs.

Update Record

Use the Update Record step to automatically update the details of an existing ServiceNow record. Map ServiceNow table columns to your custom inputs and outputs. Configure custom inputs by specifying their values manually or mapping outputs from previous steps to the inputs. At runtime, the value in the default input is used to determine the record to update.

Inputs

Inputs with an asterisk* are required, and any fields you leave blank are not updated. Custom inputs are user-provided.

Label

API mapping

Description

Record ID*

sys_id

Unique ID of the record in ServiceNow.

Outputs

These outputs are available as inputs to steps further along the flow. Custom outputs are user-provided.

Label

API mapping

Description

Record ID

 Unique record ID created by ServiceNow.
ServiceNow URL Base URL of the ServiceNow instance.
Record URL URL of the record generated by GlideSystem. Value is calculated using the endpoint URL, table name, and record ID.

ServiceNow 5.x Trigger

The built-in ServiceNow 5.x trigger initiates a flow when it receives a request from a ServiceNow webhook.

  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.

Configure ServiceNow to send requests to the trigger URL

To have ServiceNow send alerts to the flow trigger, you need to configure a webhook and set it to use the trigger URL.

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.

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 the x_xma_xmatters.xmatters_rest role (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.

Configure xMatters

Now that you've completed the first part of the configuration in ServiceNow, it's time to configure xMatters.

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.

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.

  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.

You're ready to use the webhook to trigger automated flows, including steps such as sending updates and initiating incidents, though we always recommend testing before putting things into use.

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.

  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.

ServiceNow 5.x trigger outputs

The trigger has the following outputs you can use as inputs to steps further along the flow, including values for a ServiceNow major incident. The output values depend on whether the signal came from an Incident Notification configuration or an Engage with xMatters configuration.

Label

 Description

Trigger

 Name of the ServiceNow trigger that initiated the alert.
Record ID Unique record ID created by ServiceNow.
Record Number Unique record number created by ServiceNow. For example, INC00001.
State State of the incident taken from the ServiceNow task table.
Incident State State of the incident taken from the ServiceNow incident.
Impact Impact level as set in the ServiceNow record.
Urgency Urgency level as set in the ServiceNow record.
Severity Severity of the incident as set in ServiceNow.
Priority

Priority level of the ServiceNow incident.
Major Incident State State of the ServiceNow major incident.
Major Incident Proposed By ID of the ServiceNow user that proposed the major incident.
Major Incident Proposed On Date and time the major incident was proposed.
Major Incident Promoted By ID of the ServiceNow user that promoted the incident to a major incident.
Major Incident Promoted On Date and time the ServiceNow incident was promoted to a major incident.
Opened At Date and time the ServiceNow incident was opened.
Opened By ID of the ServiceNow user that opened the incident.
Short Description Short description of the incident as provided by ServiceNow.
Description Detailed description of the ServiceNow incident. If the description exceeds 20,000 characters at runtime, it will be truncated.
Category

Category of the ServiceNow incident.
Subcategory Subcategory of the ServiceNow incident.
Configuration Item Related configuration item set in ServiceNow, if applicable.
Service Related ServiceNow service.
Assigned To ID of the user assigned to the ServiceNow incident.
Assignment Group ID of the group assigned to the ServiceNow incident.
User Assigned Boolean value indicating if a user is assigned to the ServiceNow incident.
Channel Name of the ServiceNow channel, if set.
Caller ServiceNow ID of the user that submitted the request.
ServiceNow URL Base URL of the ServiceNow instance.
Recipients

Comma-separated list of recipients.
Engage Initiator Display name of the user that initiated the ServiceNow engagement notification.
Engage Initiator Username Username of the user that initiated the ServiceNow engagement notification.
Engage Subject Subject of the ServiceNow engagement notification.
Engage Message Message of the ServiceNow engagement notification.
Engage Priority Priority level of the ServiceNow engagement notification.
Engage Task ID Unique task ID assigned by ServiceNow to the engage record.
Engage Number Unique number assigned by ServiceNow to the engage request.
Engage Conference Type Type of conference bridge requested for the engagement notification. Available values are: Bridge, External.
Engage Conference Bridge ID Conference bridge ID selected for the engagement notification.
Custom Fields

JSON object of custom fields from the ServiceNow incident with a maximum of 20,000 characters. To maintain a parsable object, any value that exceeds the character limit is excluded.