ServiceNow Connector

Connect ZenSearch to ServiceNow to index Knowledge Base articles, incidents, change requests, and problems for AI-powered search across your ITSM data.

Overview

The ServiceNow connector lets you:

• Index Knowledge Base articles (kb_knowledge) by default
• Optionally ingest incidents, change requests, and problems for full-text search
• Sync record permissions (assignment groups, owners) for permission-aware search
• Run incremental syncs using ServiceNow's sys_updated_on watermark

Prerequisites

• A ServiceNow instance you administer (production, sandbox, or developer instance)
• Either:
  • OAuth 2.0 application registered in your ServiceNow instance with grant type refresh_token, or
  • A service account with read access to the tables you want to index

Authentication

ServiceNow OAuth applications are scoped to a single instance and ZenSearch is not a registered partner application — you create your own OAuth app inside your ServiceNow instance and provide the credentials to ZenSearch.

OAuth 2.0 (Recommended)

1. In ServiceNow, navigate to System OAuth → Application Registry.
2. Click New → Create an OAuth API endpoint for external clients.
3. Set:
   • Name: ZenSearch
   • Redirect URL: any HTTPS URL you control (the OAuth dance is one-shot, run from your machine)
   • Refresh Token Lifespan: 8,640,000 seconds (100 days, the default — rotate before expiry)
4. Save and copy the generated Client ID and Client Secret.
5. Run the authorization-code flow once against https://<your-instance>.service-now.com/oauth_auth.do to obtain a refresh_token.
6. Paste the Client ID, Client Secret, and Refresh Token into the ZenSearch connector form.

ZenSearch automatically refreshes the access token before each sync.

Basic Auth (Service Account)

1. Create a dedicated ServiceNow user (e.g. zensearch_svc) with the role(s) needed to read the configured tables (typically knowledge for KB, itil for incidents/changes/problems).
2. Enter the username and password into the ZenSearch connector form.

Credentials are stored encrypted at rest using AES-GCM.

Configuration

Setting	Description
Instance URL	Your ServiceNow instance, e.g. https://dev12345.service-now.com
Authentication Method	OAuth 2.0 (recommended) or Basic Auth
Tables	Tables to index. Default: [kb_knowledge]. Optional: incident, change_request, problem, kb_category
Modified After	ISO 8601 datetime — only sync records updated after this date (uses sys_updated_on)
Additional Encoded Query	Optional ServiceNow encoded-query string AND-ed with the watermark, e.g. active=true^priority<=2
Include Permissions	Sync assigned_to / assignment_group / opened_by as permissions for permission-aware search
Page Size	Records per Table API page (1–1000, default 100)
Max Records per Table	Upper bound per table (default 100,000; set 0 to use the default)

Setup Steps

1. Add Connector: Knowledge → Add Data Source → ServiceNow
2. Authenticate: choose OAuth or Basic Auth and provide credentials
3. Select Tables: leave default (kb_knowledge) or opt in to ITSM tables
4. Set Filters: optional Modified After watermark and encoded-query filter
5. Test & Create: ZenSearch validates the credentials against your instance

Tables Indexed

Table	Default	Content
kb_knowledge	✅	Knowledge Base articles (title, body, category)
incident	opt-in	Incident records (short description, description, work notes)
change_request	opt-in	Change requests (short description, description, planned dates)
problem	opt-in	Problem records
kb_category	opt-in	KB taxonomy / categories

Each ingested record links back to the source via nav_to.do URLs that ZenSearch surfaces in search results.

Encoded Query Filtering

The Additional Encoded Query field accepts ServiceNow's encoded-query syntax (the same string you'd see in the URL of a list view after filtering):

active=true^priority<=2^category=software

Examples:

• active=true — only active records
• state!=6 — exclude resolved
• kb_knowledge_base=cf09e24b0bf340109c2cf306d5673a2c — only one KB base

The collector AND-s your query with the sys_updated_on watermark, so incremental syncs still respect both.

Permission Sync

When Include Permissions is enabled, ZenSearch derives permissions from each record's:

• assigned_to — record owner
• opened_by — record creator
• assignment_group — owning group

These map to ZenSearch's allowed_users / allowed_groups so search results are filtered to what each user can see in ServiceNow. KB articles additionally surface their kb_knowledge_base as a group affiliation.

note

ServiceNow's full ACL evaluation is dynamic (per-query, per-user). ZenSearch ingests the static permission signals listed above; complex Read ACLs that depend on runtime context (e.g. business hours, scripted conditions) are not modeled. For high-sensitivity data, enable Strict permission enforcement in your team settings so unmapped records are excluded by default.

Best Practices

1. Start with kb_knowledge only — it's the highest-value content for search.
2. Use the Modified After watermark on the first sync to bound history (e.g. last 12 months).
3. For instances under heavy ACL load, lower Page Size to 50–100 to keep response times under 30s.
4. Rotate the OAuth refresh token before its 100-day expiry to avoid sync failures.
5. Enable Include Permissions if your KB has sensitive articles restricted by user-criteria.

Troubleshooting

OAuth returns invalid_grant: refresh token has expired (default 100 days). Run the authorization-code flow again to mint a new token and update the connector.

Empty results despite records existing: check the connector user has the appropriate role (knowledge for KB, itil for ITSM). The collector queries the Table API as the authenticated user, so ACLs apply.

HTTP 429 / rate-limit errors: ServiceNow enforces per-user concurrent transaction and hourly limits. Lower Page Size or reduce Max Records per Table. The collector also retries automatically with exponential backoff.

Reference fields appear as {display_value, value}: this is intentional — the collector normalizes display values into search content while keeping the raw sys_id available for permission joins.

Related

• Salesforce
• Confluence
• Jira