ServiceNow steps
Flow Designer has built-in ServiceNow steps to help you integrate ServiceNow into your alert management and incident response flows.
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.
- Create Record: automatically create any ServiceNow record type, populating it with information from the alert or any previous steps in the flow.
- 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.
Adding ServiceNow steps to your flow
- 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.
- 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.
- 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.
- 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.
Create Incident inputs and outputs
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.
Update Incident inputs and outputs
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.
Add Comment inputs and outputs
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.
Send Integration Update inputs and outputs
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.
Create Record
Use the Create Record step to automatically create a record in ServiceNow. Map ServiceNow table columns to your custom inputs and outputs. Configure inputs by specifying their values manually or mapping outputs from previous steps to the inputs. At runtime, the values in the inputs are used to fill in the record.
Create Record inputs and outputs
Inputs
This step has no default inputs. Inputs required by ServiceNow will automatically be included, and you must provide values for them. Custom inputs are user-provided.
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. |
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 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.
Update Record inputs and outputs
Inputs
Inputs with an asterisk* are required, and any fields you leave blank are not updated. Inputs required by ServiceNow will automatically be included, and you must provide values for them. 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. |