ServiceNow

IT Service Management

Overview

The ServiceNow Connector integrates with the ServiceNow IT Service Management platform via the ServiceNow REST Table API. It synchronizes Configuration Management Database (CMDB) records — computers, servers, virtual machines, network gear, printers, mass-storage devices, communication devices, clusters, generic hardware, applications, and business services — along with users, groups, group memberships, locations, tasks, and configuration-item relationships. It can also discover and sync any additional ServiceNow table configured by the customer. The connector reads each table's sys_dictionary schema at runtime, so synced attributes are driven by the live ServiceNow table definitions. Computer-derived records are additionally normalized into the Brinqa unified Host model.

The connector also supports creating, updating, and deleting records in ServiceNow tables.

Data retrieved from ServiceNow

Connector Object	Required	Maps to Data Model
Computer	Yes	Host
Hardware	Yes	Hardware
User	Yes	User
Group	Yes	Group
Group Member	Yes	Group Member
Location	Yes	Location
Business Service	Yes	Business Service
Application	Yes	Application
Server	Yes	Host
Virtual Machine	Yes	Virtual Machine
Network Gear	Yes	Network Gear
Printer	Yes	Printer
Mass Storage Device	Yes	Mass Storage Device
Communication Device	Yes	Communication Device
Cluster	Yes	Cluster
Task	Yes	Task
CI Relationship	Yes	CI Relationship
Custom Tables	Yes	Custom Tables
Custom Views	Yes	Custom Views

Model relationships

note

For detailed steps on how to view the data retrieved from ServiceNow in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select ServiceNow from the Connector dropdown and provide the following:

Setting	Required	Default	Description
ServiceNow URL	No	—	ServiceNow server url
User name	No	—	User with access to read and optionally create and update records.
Password	No	—	User password.
Client ID	No	—	(Optional) Client id for OAuth application. When specified, the connector will use OAuth auth, otherwise it will revert to Basic auth using the provided \
Client secret	No	—	(Optional) Client secret for OAuth application
Additional tables	No	—	A comma-separated list of table names you wish to include in addition to the built-in tables, e.g. u_application_sec
Additional views	No	—	A comma-separated list of views you wish to include in addition to the built-in tables, e.g. u_application_sec
Page size	No	—	Maximum number of results to return per page
Parallel requests	No	—	Maximum number of parallel API requests
Maximum retries	No	—	Maximum number of retry attempts before giving up a request
Cache schema	No	—	Use cached schema

Authentication

The connector supports two authentication methods, selected automatically:

• OAuth2 (Resource Owner Password Credentials grant) — used when a Client ID and Client Secret are configured.
• HTTP Basic — used when no Client ID/Secret is configured; the username and password are Base64-encoded into the Authorization: Basic header on every request.

OAuth2 token request

Method	URL
POST	{ServiceNow URL}/oauth_token.do

Request headers:

Header	Value
Content-Type	application/x-www-form-urlencoded
Accept	application/json

Request body (form-encoded):

{
  "grant_type": "password",
  "client_id": "{Client ID}",
  "client_secret": "{Client Secret}",
  "username": "{Username}",
  "password": "{Password}"
}

Sample response:

{
  "access_token": "HLZ6xZCgGwfOG2Z3PDE3O92-88_DedFo_jcT5VHJxugcnNu5FvYXqKhyvp_SwK8v81RF9qSG4A7Tt8Lk8rja2g",
  "refresh_token": "M3zT2Q9Te8wlMue0sy-LX4_ah1ZnkpdbaI0eDz__DhutqYRaIxLLiDjig-z7lSeSmGaUzCqG2zzoHh3_K0C7UA",
  "scope": "useraccount",
  "token_type": "Bearer",
  "expires_in": 1799
}

Response fields:

Field	Description
access_token	Bearer token used to authorize subsequent API requests.
refresh_token	Token that can be used to obtain a new access token.
scope	OAuth scope granted to the token.
token_type	Token type; always Bearer.
expires_in	Token lifetime in seconds (default 1799, ~30 minutes).

Using the credential

For OAuth2, the connector caches the access token and sends it as Authorization: Bearer {access_token} on every API call. The token is refreshed automatically when it is missing or within 5 seconds of expiry. For Basic auth, every request carries Authorization: Basic {base64(username:password)}. All requests also set Accept: application/json.

Connection test

Connectivity is verified with a lightweight aggregate call:

GET /api/now/stats/sys_dictionary?sysparm_limit=1&sysparm_count=true

Sync Behavior

Incremental sync (since): when a sync token is supplied, all models append a sys_updated_on >= javascript:gs.minutesAgoStart(N) clause to the query (the User role-based query filters on user.sys_updated_on). N is the number of minutes since the prior sync, so each model filters on the record's last updated timestamp. When no sync token is supplied, a full retrieval is performed.

Common request behavior for record syncs (Table API): sysparm_display_value=all, sysparm_exclude_reference_link=true, sysparm_suppress_pagination_header=true, paged via sysparm_limit/sysparm_offset.

All table-based models are handled by a common sync layer and therefore support the same operation options (passed through OperationOptions):

Option	Description
query / QUERY	Encoded ServiceNow query appended to the sync/search filter.
attributesToGet	Comma-separated list of columns to fetch (always includes sys_id).
pageSize	Records per page (overrides configured Page size).
parallelismLevel	Parallel request count (overrides configured Parallel requests).
maxRetries	Max retry attempts (overrides configured Maximum retries).
reference_fields	Comma-separated reference columns to emit as the raw value instead of the display value.
date_formats	Pipe-separated date patterns used to parse datetime columns.
exclude_reference_link	Sets sysparm_exclude_reference_link (default true).
suppress_pagination_header	Sets sysparm_suppress_pagination_header (default true).
lower_case_name	Lower-cases the name attribute (default true); not applied to Computer/Hardware models.

How to obtain ServiceNow credentials

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:

1. Log in to your organization's ServiceNow server as an administrator.

2. Navigate to All > User Administration > Users.

3. Click New.

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

   

5. Click Submit.

6. Locate the new user in the Users table, and click the user ID.

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

8. Click Close in the "Set Password" dialog, and then click Update.

   Copy the User ID and the Password into the corresponding fields in the integration configuration.

Note: 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:

1. Locate the new user in the Users table and click the user ID.

2. Locate the Roles section on the page and click Edit.

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

Warning: sys_dictionary is a required permission and is necessary for the ServiceNow connector to function properly, as it allows Brinqa to access and view your ServiceNow tables and retrieve the schema details in these tables from your ServiceNow instance.

Note: The * permissions grant access to both the table and all extensions of that table.

Your roles should resemble the following:

4. Click Save.

Note: 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 supports OAuth2 authentication using the Password grant type. 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:

1. Log in to your organization's ServiceNow server as an administrator.

2. Navigate to All > System OAuth > Application Registry.

3. Click New.

4. Click Create an OAuth API endpoint for external clients. A new page appears.

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

6. Click Submit.

   You are taken back to the Application Registries page.

7. Click the name of the new OAuth2 client in the table.

8. Click Toggle Password Visibility next to the Client Secret field to reveal the secret.

   

   Copy the Client ID and Client Secret values and paste them into the Client ID and Client secret fields in the connector configuration. Although you can return to this page to view the Client ID and Client secret, you should handle them with care by ensuring that they are stored in a secure location.

Note: If you do not have the permissions to create the credentials for OAuth2 authentication, contact your ServiceNow administrator. For additional information, see ServiceNow documentation.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Computer

Source Field Name	SDM Attribute
first_discovered	First seen
fqdn	Dns names
fqdn	Public dns names
fqdn	Private dns names
ip_address	Ip addresses
ip_address	Public ip addresses
ip_address	Private ip addresses
last_discovered	Last seen
mac_address	Mac addresses
name	Hostnames
name	Name
operational_status	Status
os	Operating system
serial_number	Serial number
short_description (falls back to asset, model_id, os, sys_class_name)	Description
sys_class_name	Categories
sys_created_on	Source created date
sys_dictionary columns	(dynamic columns)
sys_id	Uid
sys_updated_on	Source last modified

Hardware

Source Field Name	SDM Attribute
ip_address	Ip addresses
ip_address	Public ip addresses
ip_address	Private ip addresses
sys_dictionary columns	(dynamic columns)
sys_id	Uid

User

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Group

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Group Member

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Location

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Business Service

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Application

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Server

Source Field Name	SDM Attribute
first_discovered / last_discovered	First seen / Last seen
fqdn	Dns names / Public dns names / Private dns names
ip_address	Ip addresses / Public ip addresses / Private ip addresses
mac_address	Mac addresses
name	Hostnames
name	Name
operational_status	Status
os	Operating system
serial_number	Serial number
short_description (with fallbacks)	Description
sys_class_name	Categories
sys_created_on / sys_updated_on	Source created date / Source last modified
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Virtual Machine

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Network Gear

Source Field Name	SDM Attribute
ip_address	Ip addresses / Public ip addresses / Private ip addresses
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Printer

Source Field Name	SDM Attribute
ip_address	Ip addresses / Public ip addresses / Private ip addresses
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Mass Storage Device

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Communication Device

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Cluster

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Task

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

CI Relationship

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Custom Tables

Source Field Name	SDM Attribute
sys_dictionary columns	(dynamic columns)
sys_id	Uid

Custom Views

Source Field Name	SDM Attribute
derived from *_sys_id columns	Uid
member-table sys_dictionary columns	(dynamic columns)

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Computer

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Hardware

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

User

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Group

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Group Member

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Location

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Business Service

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Application

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Server

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Virtual Machine

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Network Gear

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Printer

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Mass Storage Device

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Communication Device

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Cluster

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Task

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

CI Relationship

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Custom Tables

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Custom Views

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

• Type: See connector README

Changelog

Changelog

The ServiceNow connector has undergone the following changes:

Version	Description	Migration Steps
3.3.0	New Features - Database view support (Additional views): A new Additional views configuration property accepts a comma-separated list of ServiceNow database view names. Each configured view is exposed as its own model, independent of the existing Additional tables configuration — the connector resolves the view, merges the column definitions of its underlying tables, and syncs the joined records, so data spread across multiple tables can be ingested through a single view. Improvements - Stable identifiers for view records: Database view records do not carry a single sys_id field. The connector now derives a stable unique identifier for each view record by combining the sys_id values of the view's joined tables, so records sourced from database views are identified and tracked correctly across syncs. Records from regular tables continue to use their sys_id directly, unchanged. - Warning for unresolved custom tables and views: If a name configured under Additional tables or Additional views cannot be matched to a ServiceNow table or database view, the connector now logs a warning identifying the entry instead of silently skipping it, making misconfigurations easier to diagnose. - Corrected the wording of the validation message shown when a numeric configuration property is set to zero or a negative value.	N/A
3.2.9	Bug Fixes - Fixed an attribute type mismatch on date fields for the Computer and Server models where date values were not always parsed as timestamps.	• Computer: Date attributes (First Seen, Last Seen, Source Created Date, Source Last Modified) may contain string values instead of timestamps from previous syncs — Action: purge and re-sync • Server: Inherits the same date attribute fix from Computer — Action: purge and re-sync
3.2.8	Improvements Dependency Upgrades - Upgraded internal framework and model libraries to the latest stable versions for improved reliability, security patches, and alignment with the rest of the connector platform.	N/A
3.2.7	New Features - Added a dedicated Hardware model that synchronizes the ServiceNow cmdb_ci_hardware table and its extending tables, with IP-address handling for hardware configuration items.	N/A
3.2.6	Improvements Dependency Upgrades - Upgraded internal framework and model libraries to the latest stable versions for improved reliability, security patches, and alignment with the rest of the connector platform.	N/A
3.2.5	Improvements - Expanded and clarified the connector documentation covering authentication, supported models, and configuration options.	N/A
3.2.4	Improvements - Improved how table schema and field types are resolved so a wider range of ServiceNow column types are mapped to the correct attribute types.	N/A
3.2.3	Bug Fixes - Improved handling of field values when reading certain table columns so that values are mapped more reliably.	N/A
3.2.2	Improvements - Refined field-type detection so ServiceNow column types are mapped to the correct attribute types (boolean, integer, long, and decimal) more accurately.	• All models: Some attributes that were previously stored as text are now stored with their correct data types as the field-type mapping was corrected — Action: purge and re-sync affected models
3.2.1	Bug Fixes - Fixed the display value returned for certain reference fields so the human-readable value is shown instead of the raw identifier.	N/A
3.2.0	New Features - Added a Reference fields option that lets you choose which reference fields are synced as their underlying sys_id instead of the default display value. Improvements - ServiceNow column types are now mapped to their corresponding attribute data types — boolean, integer, long, and decimal values are stored with the correct type instead of as plain text.	• All models: Attributes backed by boolean, integer, long, or decimal ServiceNow columns are now stored as typed values rather than text — Action: purge and re-sync affected models
3.1.4	Bug Fixes - Added a null-value check when building create and update request payloads to prevent errors on records with missing field values.	N/A
3.1.3	Improvements - Improved date handling when creating and updating ServiceNow records so date and time values are formatted correctly.	N/A
3.1.2	Improvements - Normalized the name attribute to lowercase so records consolidate more reliably when only the name is available for matching.	• All models: The name attribute is now stored in lowercase, which changes previously synced values — Action: re-sync affected models
3.1.1	Improvements - Clarified the User name configuration help text to make the expected value easier to understand.	N/A
3.1.0	New Features - Added Group, Group Member, Mass Storage Device, and Server models to synchronize ServiceNow user groups, group memberships, mass-storage configuration items, and servers. Improvements - Streamlined the set of built-in tables to those most commonly used and now loads table schemas in parallel for faster syncs.	N/A
3.0.6	Improvements - Simplified field-selection logic and added support for overriding which attributes are retrieved on a per-sync basis using the attributes-to-get option.	N/A
3.0.5	New Features - Added FQDN as a recognized attribute, mapped to public and private DNS names and normalized to lowercase. Improvements - Added options to limit syncing to user-provided table names and to control which fields are retrieved per sync.	N/A
3.0.4	Improvements - All date and time attributes are now synced as proper timestamps instead of numeric values, so date fields are consistently usable across all models.	• All models: Date and time attributes are now stored as timestamps rather than numeric values, changing previously synced values — Action: purge and re-sync affected models
3.0.3	Improvements - Hostname values are now normalized for consistency across synced records.	• Computer: Hostname values are now normalized, which changes previously synced values — Action: re-sync the Computer model
3.0.2	Bug Fixes - MAC address values are now normalized, and null or empty values are skipped instead of being stored.	N/A
3.0.1	Improvements - Made OAuth authentication optional and added support for syncing additional, customer-configured ServiceNow tables. Bug Fixes - Date fields that cannot be parsed now store a null value instead of an empty string, improving data consistency.	N/A
3.0.0	Overview The ServiceNow connector integrates with the ServiceNow IT Service Management platform to synchronize Configuration Management Database (CMDB) records — including computers, virtual machines, network gear, printers, communication devices, and clusters — along with users, locations, business services, applications, tasks, and configuration-item relationships. Synced attributes are driven by each table's live ServiceNow schema, and customers can configure additional tables to sync. Category: IT Service Management Models	N/A