ServiceNow Database Instance
Sync Type: Incremental
Overview
The ServiceNow Database Instance input fetches data from the ServiceNow Table API. ServiceNow uses CMDB (Configuration Management Database) to build a logical representation of assets, services, and the relationships between them that comprise the infrastructure of your organization. This input accesses data from the cmdb_ci_db_instance table, which records database instance inventory including database type, version, configuration parameters, and connection details for both physical and cloud-hosted databases.
Prerequisites
Monad authenticates to ServiceNow using the OAuth 2.0 client credentials grant. You need:
- A ServiceNow user with the
security_admin(oradmin) role to configure OAuth. - A dedicated service account user that the OAuth client will run as, with the roles needed to read the tables you want to ingest.
- Your ServiceNow instance name (the subdomain of your instance URL — e.g. for
https://dev279154.service-now.com/, the instance name isdev279154). - Monad connects to
https://<instance name>.service-now.com. Instances reachable only on another domain are not supported.
Setup
Create the OAuth Application User
The client_credentials grant has no interactive user, so the token runs as a dedicated user configured on the OAuth client record. This user does not need a password — the OAuth client authenticates via its client ID and secret.
-
In ServiceNow, navigate to All → search for
Users→ select Users under System Security > Users and Groups. -
Click New, fill out User ID, First name, Last name, and Email, and click Submit.
-
Open the user record you just created.
-
Under the Roles tab, click Edit and add the roles the ingestion tables require. Common role mappings:
Table family Required role Change requests, incidents, problems itilCMDB ( cmdb_ci*,cmdb_rel_ci)cmdb_readUsers, groups user_adminAudit logs ( sys_audit*)adminOther tables, including
em_event(Event Management),syseventandsyslog_transaction, are protected by their own read access controls. Give the user a role that can read them (check the table's access controls in ServiceNow), and confirm with the<table>.listcheck in Troubleshooting. -
Save the changes.
Configure the OAuth client
Follow ServiceNow's Configure an OAuth client credential grant guide to create the OAuth client. The steps below mirror the ServiceNow guide, with the Monad-specific values called out.
- Navigate to Machine Identity Console → Inbound integrations → New integration → OAuth - Client credential grant. (On instances where the Machine Identity Console is not enabled, use System OAuth → Application Registry → New → Create an OAuth API endpoint for external clients.)
- Fill in the Details form:
- Name — any label you'll recognize (e.g.
Monad). - Provider name, Comments — optional.
- Active — checked.
- OAuth Application User — select the user you created in Create the OAuth Application User. The client credentials grant runs as this user, so the token can read only what this user can read.
- Leave Client ID and Client Secret blank; ServiceNow generates them on save.
- Name — any label you'll recognize (e.g.
- Configure the Auth Scope. Leave Allow access only to APIs in selected scope unchecked. Monad calls the ServiceNow Table API (
/api/now/table/...), which is treated as an unscoped (platform) API. Restricting scope causes requests to fail withaccess to unscoped api is not allowed. On the older Application Registry form, this maps to setting Scope Restriction to Broadly scoped. - (Optional) Under Advanced Options, adjust Token Format and Access token lifespan (default
1800seconds). - Click Save, then reopen the record and note the Client ID and Client Secret — you'll enter both in the Monad input.
Enable the client credentials grant
By default, ServiceNow does not accept grant_type=client_credentials for inbound OAuth. Enable it once per instance:
- Navigate to System Properties (
sys_properties.list) and click New. - Create a property with:
- Name:
glide.oauth.inbound.client.credential.grant_type.enabled - Type:
true | false - Value:
true
- Name:
- Save.
See ServiceNow — Create system property to enable client credentials grant type.
Configuration
Settings
| Setting | Type | Required | Default | Description |
|---|---|---|---|---|
instance_name | string | Yes | - | The subdomain of your ServiceNow URL only — e.g. for https://dev279154.service-now.com/, enter "dev279154" (not the full URL). |
use_synthetic_data | bool | No | false | Generate synthetic data for testing, instead of connecting to a real data source. Defaults to an hourly cron schedule for cron-based inputs. |
backfill_start_time | date | No | - | The date to start fetching data from. If not specified, no past records will be fetched. |
Secrets
| Secret | Type | Required | Description |
|---|---|---|---|
client_id | secret | Yes | Client ID generated from ServiceNow Instance |
client_secret | secret | Yes | Client Secret generated from ServiceNow Instance |
How syncs work
Each sync collects the records created since the previous sync, in creation order (sys_created_on).
A record is collected once, as it was when Monad read it.
Later updates to that record (for example an incident changing state, or a configuration item's attributes changing) are not collected again, and deleted records are not reported.
On the first run, if Backfill start time is not set, only records created after the input starts are collected. Existing records, such as your current CMDB inventory, are not. To collect existing records, set a Backfill start time earlier than the oldest record you need.
Backfill start time only applies to the input's first run. Changing it later has no effect; to backfill again, create a new input.
Records created while a sync is running are collected by the next sync. Each request returns up to 1,000 rows.
Troubleshooting
Common Issues
-
Token exchange fails with
access_denied/server_error- Full error:
failed to get access token: {"error_description":"access_denied","error":"server_error"} - Verify the
glide.oauth.inbound.client.credential.grant_type.enabledsystem property is set totrue(see Prerequisites → Enable the client credentials grant).
- Full error:
-
Token exchange fails with
invalid_client- The Client ID or Client Secret in Monad doesn't match the OAuth client record.
- Reopen the client record in ServiceNow, copy both values again, and re-save the input's secrets.
-
access to unscoped api is not allowed(HTTP 403)- Full error:
{"error":{"message":"user not authorized","detail":"access to unscoped api is not allowed"},"status":"failure"}. - ServiceNow treats the Table API (
/api/now/table/...) as an unscoped (platform) API. - Change Scope Restriction to Broadly scoped (legacy form) or uncheck Allow access only to APIs in selected scope (Machine Identity Console).
- Full error:
-
user not authorizedon a specific table (HTTP 403)- Token exchange succeeded, but the OAuth Application User lacks the role needed to read that table.
- Common role mappings:
itilfor change requests/incidents/problems,cmdb_readfor CMDB (cmdb_ci*,cmdb_rel_ci),user_adminfor users and groups,adminfor audit logs (sys_audit*).
-
invalid table <name>(HTTP 400)- The table doesn't exist on your instance. Some tables ship with specific ServiceNow plugins (e.g.
em_eventrequires Event Management). - Switch to an available equivalent — for event log data,
syseventis available on all instances.
- The table doesn't exist on your instance. Some tables ship with specific ServiceNow plugins (e.g.
-
DNS lookup failure /
no such host- The Instance name is wrong. Enter only the subdomain — e.g.
dev279154, nothttps://dev279154.service-now.com/.
- The Instance name is wrong. Enter only the subdomain — e.g.
-
Connection succeeds but no records are ingested
- Backfill start time is later than the most recent record — clear the field or set an earlier date.
- The records you expect were created before the input's first run and no Backfill start time was set (see How syncs work).
- The table is empty for the configured window. Verify by opening
<table>.listin ServiceNow filtered to the same range. - Row-level ACLs on the OAuth Application User exclude the records. Test by opening the table as the same user in the ServiceNow UI.
-
HTTP 429 / rate limiting
- ServiceNow rate limits are configured per instance under System Definition → Rate Limit Rules.
- Raise the limit for the OAuth Application User or exclude it from the rule.
- Each sync pages through results 1,000 rows at a time, so large tables (for example
sys_audit) make many requests.
-
Updated records don't appear
- This is expected: the input collects each record once, when it is created.
- Later changes to a record, such as a state change, are not collected again (see How syncs work).
Verifying the OAuth setup with curl
Once the settings above are correct, this command should return an access_token:
Code
If this returns an access_token, the OAuth side is done and any remaining errors are table- or role-scoped.
Related Articles
Sample Record
Code
Sync frequency
By default this input polls approximately every 10 seconds, with each sync beginning after the previous one completes. A cron schedule configured on the pipeline overrides this cadence. See Input Sync Frequency for details.