ServiceNow
ServiceNow is a cloud-based, IT service management tool that provides records for incidents, problems, and assets. You can bring application, asset, business service, device, group, incident and more data from ServiceNow into Brinqa and in turn, use this information to make more informed decisions about your risk management, thus strengthening your cybersecurity posture. You can also push the remediation tickets created in the Brinqa Platform to ServiceNow.
This document details the information you must provide for the connector to authenticate with ServiceNow and how to obtain that information from ServiceNow. See create a data integration for step-by-step instructions on setting up the integration.
Required connection settings
When setting up a data integration, select ServiceNow from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate ServiceNow with Brinqa:
-
ServiceNow URL: Your organization's ServiceNow Server URL. The default format is
https://<ServiceNowServerName>.service-now.com
. -
Username and Password: The username and password associated with the ServiceNow user account, which must have permissions to access the ServiceNow API return data.
Create a ServiceNow user
For the ServiceNow connector to access the ServiceNow API, you must create a user account. To create a new ServiceNow user, follow these steps:
-
Log in to your organization's ServiceNow server as an administrator.
-
Navigate to All > User Administration > Users.
-
Click New.
-
Provide a User ID, First name, and Last name for the new user, and ensure you select Active as well. Complete the other fields as desired.
-
Click Submit.
-
Locate the new user in the Users table, and click the user ID.
-
Click Set Password and generate a new password for the user. Take note of this password and provide it to the user accessing the account.
-
Click Update.
Copy the User ID and the Password into the corresponding fields in the integration configuration.
If you do not have the permissions to create a new user, contact your ServiceNow administrator. For additional information, see ServiceNow documentation.
Assign the required roles and permissions
After you have created the ServiceNow user, you can assign the necessary roles to the user so that they have the proper permissions to retrieve data from the ServiceNow API. To assign roles to the user, follow these steps:
-
Locate the new user in the Users table and click the user ID.
-
Locate the Roles section on the page and click Edit.
-
Under Collection, select the desired roles, and then click Add.
The user account must have the following roles to successfully retrieve your ServiceNow data and tables:
data_exchange
itil
snc_platform_rest_api_access
data_exchange
is a custom role that contains read permissions to the following tables:- sys_dictionary*
- sys_dictionary
- sys_db_object*
- sys_db_object
- sys_glide_object*
- sys_glide_object
noteThe
*
permissions grant access to both the table and all extensions of that table.Your roles should resemble the following:
-
Click Save.
If you do not have the permissions to assign roles to users, contact your ServiceNow administrator. For additional information, see ServiceNow documentation about how to assign roles, create a new role, and base system roles.
(Optional) Obtain the client ID and client secret for OAuth2 authentication
The ServiceNow connector also supports OAuth2 authentication. If you want to use OAuth2 authentication, you must provide a client ID and client secret in addition to the ServiceNow username and password. To obtain the credentials, follow these steps:
-
Log in to your organization's ServiceNow server as an administrator.
-
Navigate to All > System OAuth > Application Registry.
-
Click New.
-
Click Create an OAuth API endpoint for external clients. A new page appears.
-
Provide a name for the OAuth2 client application, fill in the Client Secret field, and select Active. You can also leave the Client Secret field blank if you want the system to auto-generate one. Leave the other fields as is.
-
Click Submit.
-
Click the name of the OAuth2 client in the table.
-
Click Toggle Password Visibility next to the Client Secret field to reveal the secret.
Copy the Client ID and Client Secret values to be used in the integration configuration.
If you do not have the permissions to create the credentials for OAuth2 authentication, contact your ServiceNow administrator. For additional information, see ServiceNow documentation.
Additional settings
The ServiceNow connector contains additional options for specific configuration:
-
Client ID and Client secret: The client ID and client secret for OAuth2 access to ServiceNow. When specified, the ServiceNow connector uses OAuth2 authorization. If not specified, the ServiceNow connector reverts to basic authorization using the ServiceNow username and password provided.
-
Additional tables: A comma-separated list of additional ServiceNow tables that you wish to include in addition to the tables the connector brings in by default, e.g.
problem
,incident
,change_request
,sn_vul_vulnerability
.-
By default, the ServiceNow connector brings in the following tables:
cmdb_ci_appl
cmdb_ci_service
cmdb_rel_ci
cmdb_ci_cluster
cmdb_ci_comm
cmdb_ci_computer
sys_user_group
sys_user_grmember
cmn_location
cmdb_ci_msd
cmdb_ci_netgear
cmdb_ci_printer
cmdb_ci_server
task
sys_user
cmdb_ci_vm_instance
-
-
Page size: The maximum number of records to get per API request. The default setting is 1000. It is not recommended to go over 1000.
-
Parallel requests: The maximum number of parallel API requests. The default setting is 8.
-
Maximum retries: The maximum number of times that the integration attempts to connect to the ServiceNow API before giving up and reporting a failure. The default setting is 10.
-
Use cached schema: Select this option to allow Brinqa to use a previously stored version of the ServiceNow schema when connecting to ServiceNow. Rather than requesting the schema from ServiceNow each time a connection is established, this can speed up the connection process and reduce the load on ServiceNow.
Types of data to retrieve
The ServiceNow connector retrieves the following types of data from the ServiceNow tables through the ServiceNow Table API:
Table 1: Data retrieved from ServiceNow
Connector Object | Required | ServiceNow Table |
---|---|---|
Application | No | cmdb_ci_appl |
Business Service | No | cmdb_ci_service |
CI Relationship | No | cmdb_rel_ci |
Cluster | No | cmdb_ci_cluster |
Communication Device | No | cmdb_ci_comm |
Computer | No | cmdb_ci_computer |
Group | No | sys_user_group |
Group Member | No | sys_user_grmember |
Location | No | cmn_location |
Mass Storage Device | No | cmdb_ci_msd |
Network Gear | No | cmdb_ci_netgear |
Printer | No | cmdb_ci_printer |
Server | No | cmdb_ci_server |
Task | No | task |
User | No | sys_user |
Virtual Machine Instance | No | cmdb_ci_vm_instance |
None of the connector objects in the above table are required. You can select tables based on your specific integration needs. You can also add additional ServiceNow tables, such as incident
for ServiceNow incidents, to your integration in the additional settings section of the configuration.
Some ServiceNow objects and tables are mapped directly to data models in the Brinqa Platform. For example, Computer (cmdb_ci_computer
) is mapped to Host and Incident (incident
) is mapped to Ticket. For the other objects, you must define the mappings yourself. See Data Consolidation for additional information.
For detailed steps on how to view the data retrieved from ServiceNow in the Brinqa Platform, see How to view your data.
For additional information about ServiceNow tables, see ServiceNow documentation .
Operation options
The ServiceNow connector supports the following operation options. See connector operation options for information about how to apply them.
Table 2: ServiceNow connector operation options
Option | All Possible Values | Description | Example |
---|---|---|---|
lower_case_name | false | Retains the original case of names. By default, the ServiceNow connector converts all names to lowercase. | Key: lower_case_name Value: false . This key and value combination ensures that the original casing of names is preserved. |
reference_fields | Any ServiceNow object reference field. | Retrieves the sys_ids for specified fields instead of their display values. | Key: reference_fields Value: location,assigned_to . This key and value combination retrieves the sys_ids for the location and assigned_to fields of the Computer object, instead of their display values. |
The lower_case_names
and reference_fields
operation options can be used in conjunction with any ServiceNow tables that are retrieved by the connector. For additional information on reference fields, see ServiceNow documentation.
The option keys and values are case-sensitive as they are shown in this documentation.
APIs
The ServiceNow connector uses the ServiceNow Table API. Specifically, it uses the following endpoints:
Table 3: ServiceNow Table API endpoints
Connector Object | API Endpoint |
---|---|
Application | GET /api/now/table/cmdb_ci_appl |
Business Service | GET /api/now/table/cmdb_ci_service |
CI Relationship | GET /api/now/table/cmdb_rel_ci |
Cluster | GET /api/now/table/cmdb_ci_cluster |
Communication Device | GET /api/now/table/cmdb_ci_comm |
Computer | GET /api/now/table/cmdb_ci_computer |
Group | GET /api/now/table/sys_user_group |
Group Member | GET /api/now/table/sys_user_grmember |
Location | GET /api/now/table/cmn_location |
Mass Storage Device | GET /api/now/table/cmdb_ci_msd |
Network Gear | GET /api/now/table/cmdb_ci_netgear |
Printer | GET /api/now/table/cmdb_ci_printer |
Server | GET /api/now/table/cmdb_ci_server |
Task | GET /api/now/table/task |
User | GET /api/now/table/sys_user |
Virtual Machine Instance | GET /api/now/table/cmdb_ci_vm_instance |
Changelog
The ServiceNow connector has undergone the following changes:
3.2.3
- Added a new operation option:
lower_case_name
.
3.2.2
- More updates to handle ServiceNow reference field types correctly.
3.2.0
-
Added a
reference_fields
operation option in the Computer object.This option supports obtaining ServiceNow reference fields as sys_id rather than their display values.
-
Removed the
display_value
operation option from the Computer object. -
Added methods to convert text from ServiceNow to their appropriate types, such as Boolean, Integer, or Long. (The Servicenow API returns all field values as text or string.)
3.1.4
- Added a check for null values.
3.1.3
- Improved its handling of dates when creating and updating records.
3.1.2
- Normalized names for data consolidation.
3.1.1
- Provided better help messages.
3.1.0
-
Reduced the ServiceNow source tables to only the most commonly-used ones.
-
Improve performance by loading all table schema in parallel.
-
Added additional connector objects, such as Group, Group Member, Mass Storage Device, and Server.
3.0.5
- Added FQDN as a source attribute and map it to DNS names.
3.0.4
- displayed all date and time values in the Date format.
3.0.0
- Initial Integration+ release.