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.

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

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

2. In the Roles section, click Edit.

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

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.

2. 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.
3. 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

Reference Fields

Dropdown Fields Containing Strings

Dropdown Fields and Fields Containing Integers

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.

Boolean Fields

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.