ServiceNow

You can create, search, update, and manage ServiceNow incidents with the ServiceNow plugin for InsightConnect . Additionally, you can also use this plugin to monitor and process incident changes in a Rapid7 InsightConnect workflow.

To use the ServiceNow plugin, use an existing user account or create a dedicated user account to configure the connection in InsightConnect. For more information on the functionality of the ServiceNow plugin, see the Extension Library listing .

Create a user

Log in to your ServiceNow instance with a user that has an admin role.
Once logged in, select User Administration by typing it in the Filter navigator.
Click Users > New.

Name your user in a way that indicates its purpose to help keep track of it, fill any other required fields, and click Submit.

Assign a role

Different plugin actions require different permissions. For more information about permissions required and to find which role is needed for which action, please refer to the ServiceNow documentation .

From the panel on the right side of your screen, click User Administration > Users. Open the newly created user record.

In the Roles section, click Edit.

From the Collection list, select the desired roles. Add them using arrows, and click Save.

Configure the ServiceNow connection in InsightConnect

Now that you’ve created your user in ServiceNow, you can configure the ServiceNow connection in InsightConnect to use the plugin.

In InsightConnect, open the connection configuration for the ServiceNow plugin.
- You can do this when selecting the ServiceNow plugin during a workflow building session, or by creating the connection independently by choosing Plugins & Tools from the Settings tab on the left menu. On the Plugins & Tools page, select the Connections tab and click Add Connection in the upper-right corner.

Configure the connection for the ServiceNow plugin.
- Give the connection a unique and identifiable name, select where the plugin should run, and choose the ServiceNow plugin from the list. If it’s not available, import the plugin from the Installed Plugins tab.
Configure your ServiceNow credentials.
- In the credentials field, select existing ServiceNow credentials or enter a newly created username and password.
- In the ServiceNow URL field enter the full URL to your instance of ServiceNow.

Test your connection

When you save the connection, the connection test will attempt to authenticate to the specified ServiceNow instance. A blue circle on the Connection tile indicates that the Connection test is in progress.

Successful connection tests

If there is no circle, the connection succeeded and you’re ready to begin orchestrating your processes with ServiceNow.

Failed connection tests

A red circle indicates that the connection test failed. If this occurs, check your connection details (including the ServiceNow URL, username, and password) before trying again.

The log may contain useful troubleshooting information. First, click View to see a list of your recent connection tests.

Under the Test Status tab, expand the dropdown for the test that encountered an error to view its log.

ServiceNow Queries

Certain actions and triggers in the Rapid7 ServiceNow plugin allow you to query your ServiceNow instance to find the information you need.

Query Syntax

The query syntax in ServiceNow is as follows: (field)(operator)(value).

The field can be any field that exists within the table you wish to query, that the user credentials used for the plugin has access to. A commonly used table is the incident table - both the Search Incident action and Incident Created triggers query against that table. If you wish to query another table within your ServiceNow instance, you can use the Search CI action which allows you to specify the table name as one of its inputs.

Commonly used query field names:

number
sys_created_by
sys_created_on
sys_updated_by
sys_updated_on
impact
urgency
short_description
description
priority
assigned_to
active
caller_id

Please see the table below for commonly used ServiceNow query operators and query examples for each of the field types:

String Fields

Query Operator	Description	Sample Query	Expected Result
`STARTSWITH`	Starts with	`short_descriptionSTARTSWITHPotential Phish`	All records where Short Description field starts with “Potential Phish”
`LIKE`	Contains	`descriptionLIKEreceived an email`	All records where “received an email” appears anywhere in the Description field
`NOTLIKE`	Does not contain	`short_descriptionNOTLIKEmalware`	All records where “malware” does not appear anywhere in the Short Description field
`=`	Is	`short_description=Potential Phishing Email`	All records where Short Description field is “Potential Phishing Email”
`ISEMPTY`	Is empty	`descriptionISEMPTY`	All records where Description field is empty
`ISNOTEMPTY`	Is not empty	`descriptionISNOTEMPTY`	All records where Short Description field is not empty

Reference Fields

Query Operator	Description	Sample Query	Expected Result
`ISEMPTY`	Is empty	`caller_idISEMPTY`	All records where Caller field is empty
`ISNOTEMPTY`	Is not empty	`caller_idISNOTEMPTY`	All records where Caller field is not empty
`STARTSWITH`	Starts with	`caller_idSTARTSWITHExample`	All records where the name in Caller field starts with “Example”
`ENDSWITH`	Ends with	`caller_idSTARTSWITHUser`	All records where the name in Caller field starts with “User”
`=`	Is	`caller_id=6816f79cc0a8016401c5a33be04be441`	All records where Caller is “Example User” - GUID in example belongs to “Example User”

Dropdown Fields Containing Strings

Query Operator	Description	Sample Query	Expected Result
`=`	Is	`subcategory=antivirus`	All records where Subcategory dropdown field is set to “Antivirus”
`!=`	Is not	`subcategory!=antivirus`	All records where Subcategory dropdown field is not set to “Antivirus”
`IN`	Is one of	`categoryINsoftware,network,database`	All records where Category dropdown field is set to either “Software”, “Network” or “Database”

Dropdown Fields and Fields Containing Integers

Query Operator	Description	Sample Query	Expected Result
`=`	Is	`urgency=1`	All records where Urgency dropdown field is set to “1 - High”
`!=`	Is not	`urgency!=1`	All records where Urgency dropdown field is not set to “1 - High”
`IN`	Is one of	`impactIN1,2`	All records where Impact dropdown field is set to either “1 - High” or “2 - Medium”
`<`	Less than	`impact<1`	All records where Impact dropdown field is set to less than “1 - High”
`\<=`	Less than or equal to	`impact\<= 1`	All records where Impact dropdown field is set to less than or equal to “1 - High”
`>`	More than	`impact>3`	All records where Impact dropdown field is set to higher than “3 - Low”
`>=`	More than or equal to	`impact>=2`	All records where Impact dropdown field is set to higher than or equal to “2 - Medium”
`BETWEEN`	Between	`urgencyBETWEEN1@2`	All records where Urgency dropdown field is set to between “1 - High” and “2 - Medium”

Numeric Fields

Numeric fields support all the popular operators described in Dropdown Fields and Fields Containing Integers and more. Below are some more popular examples of query operators.

Query Operator	Description	Sample Query	Expected Result
`SAMEAS`	Same as field	`reassignment_countSAMEASreopen_count`	All records where Reassignment Count value is the same as Reopen Count
`NSAMEAS`	Not same as field	`reassignment_countNSAMEASreopen_count`	All records where Reassignment Count value is not the same as Reopen Count
`GT_FIELD`	Greater than field	`reopen_countGT_FIELDreassignment_count`	All records where Reopen Count value is greater than Reassignment Count
`LT_FIELD`	Less than field	`reopen_countLT_FIELDreassignment_count`	All records where Reopen Count value is less than Reassignment Count

Boolean Fields

Query Operator	Description	Sample Query	Expected Result
`=`	Is	`active=true`	All active records
`!=`	Is not	`knowledge!=true`	All records that do not have related knowledge article
`SAMEAS`	Same as field	`made_slaSAMEASactive`	All records where value of Made SLA is the same as the record’s active status
`NSAMEAS`	Not same as field	`made_slaNSAMEASactive`	All records where value of Made SLA is not the same as the record’s active status

In addition to the above, you can join multiple queries with the following operators:

^ - And - All condition must be met for the item to be returned
^OR - Or - At least one condition must be met for the item to be returned

For the full list of operators, please refer to ServiceNow Documentation page - Operators available for filters and queries .