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.
Certain actions and triggers in the Rapid7 ServiceNow plugin allow you to query your ServiceNow instance to find the information you need.
The query syntax in ServiceNow is as follows:
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:
Please see the table below for commonly used ServiceNow query operators and query examples for each of the field types:
|All records where Short Description field starts with "Potential Phish"
descriptionLIKEreceived an email
|All records where "received an email" appears anywhere in the Description field
|Does not contain
|All records where "malware" does not appear anywhere in the Short Description field
short_description=Potential Phishing Email
|All records where Short Description field is "Potential Phishing Email"
|All records where Description field is empty
|Is not empty
|All records where Short Description field is not empty
|All records where Caller field is empty
|Is not empty
|All records where Caller field is not empty
|All records where the name in Caller field starts with "Example"
|All records where the name in Caller field starts with "User"
|All records where Caller is "Example User" - GUID in example belongs to "Example User"
Dropdown Fields Containing Strings
|All records where Subcategory dropdown field is set to "Antivirus"
|All records where Subcategory dropdown field is not set to "Antivirus"
|Is one of
|All records where Category dropdown field is set to either "Software", "Network" or "Database"
Dropdown Fields and Fields Containing Integers
|All records where Urgency dropdown field is set to "1 - High"
|All records where Urgency dropdown field is not set to "1 - High"
|Is one of
|All records where Impact dropdown field is set to either "1 - High" or "2 - Medium"
|All records where Impact dropdown field is set to less than "1 - High"
|Less than or equal to
|All records where Impact dropdown field is set to less than or equal to "1 - High"
|All records where Impact dropdown field is set to higher than "3 - Low"
|More than or equal to
|All records where Impact dropdown field is set to higher than or equal to "2 - Medium"
|All records where Urgency dropdown field is set to between "1 - High" and "2 - Medium"
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.
|Same as field
|All records where Reassignment Count value is the same as Reopen Count
|Not same as field
|All records where Reassignment Count value is not the same as Reopen Count
|Greater than field
|All records where Reopen Count value is greater than Reassignment Count
|Less than field
|All records where Reopen Count value is less than Reassignment Count
|All active records
|All records that do not have related knowledge article
|Same as field
|All records where value of Made SLA is the same as the record's active status
|Not same as field
|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.