The ServiceNow Table API Source collects records from ServiceNow tables via the ServiceNow Table API.

Type: Collector (Pull) | TLS Support: Yes | Event Breaker Support: No

This Source allows Cribl Stream to selectively collect tables from ServiceNow, and simplifies common ingestion by providing a targeted configuration experience instead of requiring a custom REST Collector for each table.

The Source calls the ServiceNow Table API for a specific instance, table, and query, then converts each record into an event in Cribl Stream.

Use this Source when you want to:

• Ingest records from ServiceNow tables into Cribl Stream.
• Reduce the number of one-off REST Collectors you maintain for ServiceNow.
• Enrich other data sources with ServiceNow context or forward ServiceNow data to downstream tools such as SIEMs or observability platforms.

For advanced or highly customized workflows, you can still use the generic REST Collector as described in ServiceNow API Collection.

Prerequisites ​

Before you configure a ServiceNow Table API Source, make sure you have the following prerequisites.

ServiceNow Requirements ​

• The full URL of your ServiceNow instance (for example, https://your-instance.service-now.com).
• A service account in ServiceNow for API access.
  • At a minimum, the account must have the rest_service role to access the Table API. Depending on the tables you query, additional roles (such as itil for Task-based tables or specific cmdb_read roles) may be required.
  • Ensure the integration user has Read Access Control List (ACL) permissions for the target tables and their fields (for example, number, state, sys_updated_on).
• Credentials stored as a Cribl Stream secret (credentials secret for Basic auth, or a text secret for OAuth).

Cribl Stream Requirements ​

• An active Cribl Stream deployment with at least one Worker Group.
• A Cribl user account with stream_admin or GroupCollect permissions to configure and run collectors. For details, see Roles and Policies.
• Workers must have outbound network access to the ServiceNow instance on port 443.
• If your environment requires outbound HTTPS traffic to pass through a proxy, ensure the system proxy is configured in Cribl Stream.

Configure Cribl Stream to Collect ServiceNow Table Data ​

In Cribl Stream, configure the ServiceNow Table API Source:

1. On the top bar, select Products, and then select Cribl Stream. Under Worker Groups, select a Worker Group. Next, you have two options:

   • To configure via QuickConnect, navigate to Routing > QuickConnect. Select Add Source and select the Source you want from the list, choosing either Select Existing or Add New.
   • To configure via the Routes, select Data > Sources. Select the Source you want. Next, select Add Source.

2. In General Settings, configure:

   • Input ID: Enter a unique name to identify this Source definition. If you clone this Source, Cribl Stream will add -CLONE to the original Input ID.
   • Description: Optionally, enter a description.

3. In the Connection group, configure:

   • Instance URL: Enter the full URL of your ServiceNow instance, for example https://your-instance.service-now.com.

4. In Table Settings group, configure:

   • Table name: The ServiceNow table to collect from (for example, incident, sys_user, or cmdb_ci_appl).
   • Fields: Comma-separated list of field names to retrieve (for example, sys_id,number,short_description). Leave empty to retrieve all fields. The sys_updated_on field is always retrieved by the Source to timestamp events, even if not listed here.
   • Sort by field: Optional field to sort results by (for example, sys_created_on). Leave empty to use the server default order.
   • Sort direction: Used only when Sort by field is set. Defaults to Ascending.
   • Filter query (advanced): Optional ServiceNow encoded query for sysparm_query (for example, active=true or sys_updated_onRELATIVEGT@hour@ago@1). Accepts a literal string or a Cribl expression. When combined with Sort by field, the filter and sort are joined with ^. See ServiceNow Table API documentation for encoded query syntax.
   • Page size: Number of records per page. Defaults to 10000. Minimum is 1.
   • Page limit: Maximum number of pages to retrieve per collection task. Defaults to 100. Set to 0 to retrieve all pages.

   The Source always retrieves both display and raw values from ServiceNow (equivalent to sysparm_display_value=all). For fields such as sys_updated_on, the response includes both a display_value (in the instance’s local time zone) and a value (in UTC). Cribl Stream uses the UTC value to parse the event timestamp.

5. In Scheduling group, configure the collection schedule:

   • Cron schedule: Cron expression defining when collection runs (for example, 0 * * * * to run every hour).
   • Earliest: Start of the time range for each collection run. Defaults to -1d.
   • Latest: End of the time range. Defaults to now.
   • Job timeout: Maximum time a collection job may run before being terminated. Set to 0 for no timeout.
   • Log level: Logging verbosity for collection jobs.

6. Configure Authentication, State Tracking, and Advanced Settings as needed.

7. Select Save, then Commit & Deploy.

Authentication ​

Select the authentication method that matches your ServiceNow setup.

Authentication type supports the following options:

None: No authentication. Suitable only for ServiceNow instances with open API access.

Basic: Authenticates using a stored credentials secret containing a username and password. Exposes:

• Credentials secret: Select or create a stored credentials secret.

OAuth: Authenticates using an OAuth token request, with the client secret stored as a text secret. Exposes:

• Grant type: ServiceNow OAuth grant type used for token requests. You can select Password or Client credentials. When Password is selected, additional Username and Password fields appear for the ServiceNow account credentials.
• ServiceNow OAuth client ID: The client ID of the OAuth application registered in your ServiceNow instance.
• Client secret: Select or create a stored text secret containing the OAuth client secret value.
• Use custom parameters and/or headers: Enable custom OAuth request parameters or headers for advanced ServiceNow configurations. Leave disabled for standard ServiceNow OAuth flows.

Processing Settings ​

Fields ​

In this section, you can add Fields to each event using Eval-like functionality.

Name: Field name.

Value: JavaScript expression to determine the field’s value (can be a constant).

Pre-Processing ​

In this section’s Pipeline drop-down list, you can select a single existing Pipeline or Pack to process data from this input before the data is sent through the Routes.

Retries ​

Retry type: The retry strategy for failed requests. Defaults to Backoff.

Initial retry interval (ms): The starting wait time between retry attempts, in milliseconds. Defaults to 1000.

Retry limit: Maximum number of retry attempts per request. Defaults to 5.

Backoff multiplier: Factor by which the retry interval increases after each attempt. Defaults to 2.

Retry HTTP codes: HTTP response codes that trigger a retry. Defaults to 408, 429, 500, 502, 503, and 504.

Honor Retry-After header: When toggled on (default), Cribl Stream respects the Retry-After response header returned by ServiceNow, waiting the indicated duration before retrying.

Retry connection timeout: When toggled on, retries requests that fail due to a connection timeout. Defaults to toggled off.

Retry connection reset: When toggled on, retries requests that fail due to a connection reset. Defaults to toggled off.

Advanced Settings ​

Reject unauthorized certificates: When toggled on (default), Cribl Stream rejects TLS certificates from the ServiceNow instance that are not signed by a trusted CA. Toggle off only in development or test environments.

Time to live: Maximum lifetime for the underlying collection job before it is forcibly terminated. Defaults to 4h. Accepts duration strings such as 1h or 30m. Set to 0 for no limit.

Request timeout: Maximum time (in seconds) to wait for a response from ServiceNow. Set to 0 to wait indefinitely.

Round-robin DNS: When toggled on, Cribl Stream resolves the ServiceNow instance hostname on each request and distributes connections across all returned IP addresses. Useful when the instance URL resolves to multiple IPs behind a load balancer.

Ignore Worker Group job limits: When toggled on, this Source’s collection jobs bypass the concurrent job limits configured for the Worker Group, allowing them to run regardless of how many other jobs are already active.

Environment: If you’re using GitOps, optionally specify a single Git branch on which to enable this configuration. If empty, the config will be enabled everywhere.

Connected Destinations ​

Select Send to Routes to enable conditional routing, filtering, and cloning of this Source’s data via the Routing table.

Select QuickConnect to send this Source’s data to one or more Destinations via independent, direct connections.

State Tracking ​

You can configure the Source to track state by time. This helps prevent overlaps between collection jobs, where subsequent runs may return some of the same results as previous runs. It also helps prevent gaps in data by allowing a run to pick up from where the last run ended.

State tracking: Toggle on to enable state tracking.

State update expression: JavaScript expression that defines how to update the state from an event. Use the event’s data and the current state to compute the new state.

State merge expression: JavaScript expression that defines which state to keep when merging a task’s newly reported state with the previously saved state. Evaluates prevState and newState variables, resolving to the state to keep.

The default values for these fields are configured to track state by the latest _time field found in events gathered in a collection run.

Understanding State Expression Fields ​

The State update and State merge expressions control how state is derived from a collection run and how it is merged with existing state, respectively. They’re preconfigured to work with the common use case of tracking state by latest _time, but you may need to update them for other use cases.

State update expression ​

This expression has a default value of:

typeof _time === 'number' && !isNaN(_time) && { latestTime: (state.latestTime || 0) > _time ? state.latestTime : _time }

typeof _time === 'number' && !isNaN(_time): Checks that the event’s _time field is a finite number before updating state. Unlike some other sources, this source advances state even when the event breaker assigns a fallback time (rather than gating on __timestampExtracted), ensuring state does not stall when timestamps cannot be parsed from the raw event.

State values must resolve to an object, such as:

{ "latestTime": 1712280616 }

If the expression does not resolve to an object, Cribl Stream ignores the result.

{ latestTime: (state.latestTime || 0) > _time ? state.latestTime : _time }: Compares state.latestTime to the event’s _time value, keeping whichever value is greater.

State merge expression ​

This expression has a default value of:

prevState.latestTime > newState.latestTime ? prevState : newState

It compares prevState (the state that was previously saved) to newState (the state reported from the most recent collection task), keeping the state with the greatest latestTime value.

Managing State ​

Select Manage State to view, modify, or delete a state. For more information, see Manage State.

Troubleshooting ​

The Source’s configuration modal has helpful tabs for troubleshooting:

Live Data: Try capturing live data to see real-time events as they are ingested. On the Live Data tab, click Start Capture to begin viewing real-time data.

Logs: Review and search the logs that provide detailed information about the ingestion process, including any errors or warnings that may have occurred.

You can also view the Monitoring page that provides a comprehensive overview of data volume and rate, helping you identify ingestion issues. Analyze the graphs showing events and bytes in/out over time.

Response Errors ​

The Source treats all non-200 responses from the ServiceNow Table API as errors. This includes 1xx, 3xx, 4xx, and 5xx responses.

A few exceptions are treated as non-fatal errors:

• Where a collect job launches multiple tasks, and only a subset of those tasks fail, Cribl Stream places the job in failed status, but treats the error as non-fatal. (Note that Cribl Stream does not retry the failed tasks.)
• Where a collect job receives a 3xx redirection error code, it follows the error’s treatment by the underlying library, and does not necessarily treat the error as fatal.

The Source automatically retries requests that fail with the following HTTP status codes: 408, 429, 500, 502, 503, 504. To adjust retry behavior, see Retries.

Common Issues ​