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

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

ServiceNow User Administration

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

Create a user

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.

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

Select user

  1. In the Roles section, click Edit.

Edit roles

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

Role selection

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.

  1. 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.

Add connection in InsightConnect

  1. Configure the connection for the ServiceNow plugin.
    • Give the connection a unique and identifiable name, select the orchestrator the plugin should run on, and choose the ServiceNow plugin from the list. If it’s not available, import the plugin from the Installed Plugins tab.
  2. 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.

ServiceNow Connection

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.

In Progress

Successful connection tests

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

Success

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.

Failed

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

View recent connection test

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

View security team 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 OperatorDescriptionSample QueryExpected Result
STARTSWITHStarts withshort_descriptionSTARTSWITHPotential PhishAll records where Short Description field starts with "Potential Phish"
LIKEContainsdescriptionLIKEreceived an emailAll records where "received an email" appears anywhere in the Description field
NOTLIKEDoes not containshort_descriptionNOTLIKEmalwareAll records where "malware" does not appear anywhere in the Short Description field
=Isshort_description=Potential Phishing EmailAll records where Short Description field is "Potential Phishing Email"
ISEMPTYIs emptydescriptionISEMPTYAll records where Description field is empty
ISNOTEMPTYIs not emptydescriptionISNOTEMPTYAll records where Short Description field is not empty

Reference Fields

Query OperatorDescriptionSample QueryExpected Result
ISEMPTYIs emptycaller_idISEMPTYAll records where Caller field is empty
ISNOTEMPTYIs not emptycaller_idISNOTEMPTYAll records where Caller field is not empty
STARTSWITHStarts withcaller_idSTARTSWITHExampleAll records where the name in Caller field starts with "Example"
ENDSWITHEnds withcaller_idSTARTSWITHUserAll records where the name in Caller field starts with "User"
=Iscaller_id=6816f79cc0a8016401c5a33be04be441All records where Caller is "Example User" - GUID in example belongs to "Example User"

Dropdown Fields Containing Strings

Query OperatorDescriptionSample QueryExpected Result
=Issubcategory=antivirusAll records where Subcategory dropdown field is set to "Antivirus"
!=Is notsubcategory!=antivirusAll records where Subcategory dropdown field is not set to "Antivirus"
INIs one ofcategoryINsoftware,network,databaseAll records where Category dropdown field is set to either "Software", "Network" or "Database"

Dropdown Fields and Fields Containing Integers

Query OperatorDescriptionSample QueryExpected Result
=Isurgency=1All records where Urgency dropdown field is set to "1 - High"
!=Is noturgency!=1All records where Urgency dropdown field is not set to "1 - High"
INIs one ofimpactIN1,2All records where Impact dropdown field is set to either "1 - High" or "2 - Medium"
<Less thanimpact<1All records where Impact dropdown field is set to less than "1 - High"
<=Less than or equal toimpact<=1All records where Impact dropdown field is set to less than or equal to "1 - High"
>More thanimpact>3All records where Impact dropdown field is set to higher than "3 - Low"
>=More than or equal toimpact>=2All records where Impact dropdown field is set to higher than or equal to "2 - Medium"
BETWEENBetweenurgencyBETWEEN1@2All 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 OperatorDescriptionSample QueryExpected Result
SAMEASSame as fieldreassignment_countSAMEASreopen_countAll records where Reassignment Count value is the same as Reopen Count
NSAMEASNot same as fieldreassignment_countNSAMEASreopen_countAll records where Reassignment Count value is not the same as Reopen Count
GT_FIELDGreater than fieldreopen_countGT_FIELDreassignment_countAll records where Reopen Count value is greater than Reassignment Count
LT_FIELDLess than fieldreopen_countLT_FIELDreassignment_countAll records where Reopen Count value is less than Reassignment Count

Boolean Fields

Query OperatorDescriptionSample QueryExpected Result
=Isactive=trueAll active records
!=Is notknowledge!=trueAll records that do not have related knowledge article
SAMEASSame as fieldmade_slaSAMEASactiveAll records where value of Made SLA is the same as the record's active status
NSAMEASNot same as fieldmade_slaNSAMEASactiveAll 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.