Programmer's reference for ServiceNow Reader

Connection and authentication

Authentication type

Enum

Supported: OAuth, Manual OAuth.

Connection URL

String

Base URL of the ServiceNow instance (for example, https://your-instance.service-now.com).

Client ID

Password (encrypted)

Client ID from the ServiceNow OAuth application. Ignored when using a connection profile.

Client secret

Password (encrypted)

Client secret from the ServiceNow OAuth application. Ignored when using a connection profile.

Access token

Password

Used with Manual OAuth.

Refresh token

Password

Used with Manual OAuth to obtain new access tokens.

Username

String

User ID of a ServiceNow account (supply if required by your OAuth flow or profile).

Password

Password

Password for the specified user (if required).

Use connection profile

Boolean

False

Set to True to reference a saved connection profile.

Connection profile name

String

Name of the ServiceNow connection profile to use when Use connection profile is True.

Connection retries

Integer

3

Maximum number of connection attempts before halting.

Connection timeout

Integer

60

Socket timeout in seconds (cannot exceed 300 seconds).

Data selection and mode

Capture deletes

Boolean

False

Available only in Incremental Load and Automated modes. When set to True, the adapter captures DELETE operations from ServiceNow. Auditing must be enabled for the target tables in ServiceNow; delete events are recorded in the sys_audit_delete table only when auditing is active for the specific table. See Configuring auditing for a table in ServiceNow documentation.

Deletes that occurred before the application started are not captured. The target adapter should support NoOp deletes, as the adapter may send a DELETE operation for a record even if its corresponding INSERT was never sent.

Tables

String

Semicolon-delimited list of tables or views to read. Supports % wildcard. Do not modify when recovery is enabled.

Excluded tables

String

Optional list of tables to exclude. Wildcards are not supported.

Mode

Select list

Initial load

Controls whether to run a one-time historical sync, a continuous incremental sync, or both (Automated).

Incremental load marker

String

sys_updated_on

The field used as the watermark for incremental replication. Applies to Incremental Load and Automated modes.

The marker must be a datetime field whose value increases with every change to the record and is never empty. A field that does not increase strictly, or that contains empty values, can cause records to be missed.

To override the default, specify table-and-field pairs in the format <table_name>=<field_name>, separating pairs with semicolons. The % wildcard sets a default for all tables, which you can then override per table. For example, %=sys_updated_on;change_request=opened_at uses sys_updated_on for every table except change_request, which uses opened_at.

If the specified field does not exist in a table, the application throws an exception.

When the marker is sys_updated_on, the reader distinguishes inserts from updates by comparing sys_created_on with sys_updated_on. When any other datetime field is used as the marker, this distinction is not supported and all records are emitted as inserts.

Start timestamp

String

Optional starting point for reads. Format: YYYY-MMM-DD HH:MM:SS (UTC). If not specified for incremental mode, the reader begins near the current time.

Polling interval

String

120s

How often to poll for new/updated data. Format: integer + d/h/m/s.

Send full reference dictionary

Boolean

False

When True, reference fields are returned as a JSON structure containing display_value, link, and value keys. If a record has no corresponding reference, the JSON object contains empty values and the link key is omitted. When False, only the reference UUID is returned.

Performance and schema

Fetch size

Integer

1000

Maximum records per paginated API call for a table.

Max connections

Integer

20

Maximum connections in the HTTP client pool.

Thread pool count

Integer

10

Parallel reader threads. A practical guideline is roughly one thread per 40 tables.

The ThreadPoolCount value must be less than the number of available processors. For example, if the system has eight processors, set ThreadPoolCount to 7 or lower.

Batch API

Boolean

True

When True, groups requests for different tables into a single batch API call (subject to ServiceNow's size limits).

ServiceNow advises against including long-running requests, or requests that retrieve large amounts of data, in a batch API call. If your ServiceNow instance holds a large volume of data, set this property to False, because a batch request that exceeds the maximum transaction time fails. See Batch API in the ServiceNow documentation.

Migrate schema

Boolean

When enabled in initial load, propagates table schema to the target.