Copy page

ServiceNow

Configuration Item Relationship

Sync Type: Incremental

Overview

The ServiceNow Configuration Item Relationship input fetches data from ServiceNow Table API. ServiceNow uses CMDB (Configuration Management Database) application to build logical representation of assets, Services, and the relationships between them that comprise the infrastructure of your organization. CI relationship is an association between the service and the CIs (Configuration Items) that make up the service. This input accesess data from cmdb_rel_ci table.

Prerequisites

Monad authenticates to ServiceNow using the OAuth 2.0 client credentials grant. You need:

• A ServiceNow user with the security_admin (or admin) 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 is dev279154).

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.

1. In ServiceNow, navigate to All → search for Users → select Users under System Security > Users and Groups.

2. Click New, fill out User ID, First name, Last name, and Email, and click Submit.

3. Open the user record you just created.

4. 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	itil
   CMDB (cmdb_ci*, cmdb_rel_ci)	cmdb_read
   Users, groups	user_admin
   Audit logs (sys_audit*)	admin

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

1. 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.)
2. Fill in the Details form:
   • Name — any label you'll recognize (e.g. Monad).
   • Provider name, Comments — optional.
   • Active — checked.
   • Leave Client ID and Client Secret blank; ServiceNow generates them on save.
3. 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 with access to unscoped api is not allowed. On the older Application Registry form, this maps to setting Scope Restriction to Broadly scoped.
4. (Optional) Under Advanced Options, adjust Token Format and Access token lifespan (default 1800 seconds).
5. 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:

1. Navigate to System Properties (sys_properties.list) and click New.
2. Create a property with:
   • Name: glide.oauth.inbound.client.credential.grant_type.enabled
   • Type: true | false
   • Value: true
3. Save.

See ServiceNow — Create system property to enable client credentials grant type.

Configuration

Setting	Type	Required	Description
Instance name	string	true	Subdomain of your ServiceNow URL only — e.g. for https://dev279154.service-now.com/, enter dev279154 (not the full URL).
Client ID	string	true	Client ID of the OAuth application created in the Application Registry.
Client Secret	string	true	Client Secret of the OAuth application created in the Application Registry.
Backfill start time	string	false	The date to start fetching data from. If not specified, data is fetched from the time the input is first run.
Use synthetic data	boolean	false	Generate synthetic demo data instead of connecting to the real data source.

Troubleshooting

Common Issues

1. 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.enabled system property is set to true (see Prerequisites → Enable the client credentials grant).

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

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

4. user not authorized on a specific table (HTTP 403)

   • Token exchange succeeded, but the OAuth Application User lacks the role needed to read that table.
   • Common role mappings: itil for change requests/incidents/problems, cmdb_read for CMDB (cmdb_ci*, cmdb_rel_ci), user_admin for users and groups, admin for audit logs (sys_audit*).

5. invalid table <name> (HTTP 400)

   • The table doesn't exist on your instance. Some tables ship with specific ServiceNow plugins (e.g. em_event requires Event Management).
   • Switch to an available equivalent — for event log data, sysevent is available on all instances.

6. DNS lookup failure / no such host

   • The Instance name is wrong. Enter only the subdomain — e.g. dev279154, not https://dev279154.service-now.com/.

7. Connection succeeds but no records are ingested

   • Backfill start time is set in the future or later than the most recent record — clear the field or set an earlier date.
   • The table is empty for the configured window. Verify by opening <table>.list in 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.

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

Verifying the OAuth setup with curl

Once the settings above are correct, this command should return an access_token:

Code
curl -s -X POST "https://<instance>.service-now.com/oauth_token.do" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>"

If this returns an access_token, the OAuth side is done and any remaining errors are table- or role-scoped.

Related Articles

• ServiceNow Table API
• ServiceNow OAuth
• ServiceNow - CMDB

Sample Record

Code
{
    "child": {
        "link": "https://testxyz.service-now.com/api/now/table/cmdb_ci/339badd1-e4f5-eb3b-cfc4-ee6d66354ecd",
        "value": "54bec76a-4559-31a7-e4a1-57f6ee983ea4"
    },
    "connection_strength": "always",
    "parent": {
        "link": "https://testxyz.service-now.com/api/now/table/cmdb_ci/a02f5d4b-2422-8311-7c01-df89863f73a0",
        "value": "b09fd984-208d-ef69-f277-13f8731df2fb"
    },
    "percent_outage": "",
    "port": "",
    "sys_created_by": "admin",
    "sys_created_on": "2025-10-10T08:23:25.231Z",
    "sys_id": "9e71f9dd-808e-8f94-0ef9-be83d4a1dfb0",
    "sys_mod_count": "0",
    "sys_tags": "",
    "sys_updated_by": "admin",
    "sys_updated_on": "2025-10-10T08:23:25.231Z",
    "type": {
        "link": "https://testxyz.service-now.com/api/now/table/cmdb_rel_type/fc13398c-014f-8fc4-710a-ccc5c0e75e2b",
        "value": "ec66305a-fded-0483-2508-55cdf51532ec"
    }
}

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.