> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/connectors/servicenow.md). # ServiceNow K-AI ingests Knowledge Articles from a ServiceNow Knowledge Base via the ServiceNow Knowledge Management REST API (`/api/sn_km_api/knowledge/articles`). The connector authenticates with a service account, lists articles inside a single Knowledge Base, and syncs incrementally based on each article's `sys_updated_on` timestamp. The typical use case is making the internal IT support, HR self-service, or policy Knowledge Base searchable through K-AI MCP, with ServiceNow remaining the system of record. ## Supported source versions * **ServiceNow** — all currently supported Now Platform releases (Vancouver, Washington DC, Xanadu, Yokohama, and later). The Knowledge Management REST API is stable across releases. * **Hosted ServiceNow instances** only (`*.service-now.com`). Self-hosted on-prem ServiceNow deployments are supported when reachable from the K-AI Instance and resolvable via the configured `domain`. * **Article scope only** — the connector targets one Knowledge Base (`kb`) per source registration. To ingest multiple Knowledge Bases, register one source per KB. Catalog Items and Incidents-with-attachments are not ingested by this connector; raise the requirement with the K-AI integration team for a custom driver. ## Authentication The connector uses **HTTP Basic authentication** with a ServiceNow service account (user + password). The service account must hold: * The `snc_internal` role (or equivalent) to call `/api/sn_km_api/knowledge/articles`. * Read access to the target Knowledge Base — granted via ServiceNow **user criteria** on the KB record (the service account must satisfy the KB's `can_read_user_criteria`). * The `knowledge` role for KBs that are not configured for `Public` read. OAuth 2.0 is not exposed in the current connector. Customers that prefer OAuth (recommended for production) can wire a token endpoint through the [Generic HTTP](/knowledge-ai/sources-and-ingestion/connectors/generic-http.md) connector instead, or request the OAuth-capable variant from the K-AI integration team. ## Configuration | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `domain` | string | yes | ServiceNow tenant domain, e.g. `contoso.service-now.com` for `https://contoso.service-now.com/...`. Do not include the URL scheme. | | `user` | string | yes | Username of the ServiceNow service account. | | `password` | string | yes | Password of the ServiceNow service account. Encrypted at rest by the platform. | | `db` | string | yes | `sys_id` of the target Knowledge Base (the `kb` parameter passed to the Knowledge API). | The connector derives the source host (`{domain}`) and registers it in the K-AI host allow-list. ## Document types ingested The Knowledge API returns articles as HTML body plus structured metadata. The connector ingests: * **Knowledge Articles** — body extracted as HTML; converted to text during the indexation step. * **Article attachments** — PDF, Word, Excel, PowerPoint, plain text, and images embedded in or linked from articles. Pulled through `/api/now/attachment/{sys_id}/file` with the same service account credentials. * **Article metadata** — `short_description`, `topic`, `category`, `author`, `kb_knowledge_base`, `workflow_state`, `published`, `valid_to` — mapped to the K-AI document's structural metadata. Only articles in `workflow_state = 'published'` are ingested by default. Articles in `draft`, `review`, or `retired` are filtered out at listing time. ## Sync mode Incremental sync uses the **`sys_updated_on` filter** on `/api/sn_km_api/knowledge/articles`. The connector persists the latest `sys_updated_on` value seen on a successful run and passes it as the lower bound on the next cycle. Only articles updated since the cursor are re-downloaded. Deletions and retirements are detected on each cycle by issuing a full enumeration of `sys_id` against the KB and comparing with the previous snapshot. Articles whose `workflow_state` transitions to `retired` are marked deleted on the K-AI side; they are not physically purged from ServiceNow. The first sync is a full crawl with no `sys_updated_on` lower bound. Subsequent syncs are incremental. ## ACL handling ServiceNow's KB access model is **user criteria** + **roles** — a Knowledge Base has `can_read_user_criteria` and `cannot_read_user_criteria` rules expressed as roles, groups, departments, locations, or scripted criteria. There is no API surface that exposes a flat ACL per article. The connector applies the configured **mapped** ACL strategy: a group rule attached at source-registration time is propagated to every article ingested from the KB. This means the K-AI source typically maps one KB to one consumer group (e.g. `it-support` for the IT KB, `hr-employees` for the HR KB). For finer-grained access control, partition articles into separate KBs by audience, register one K-AI source per KB, and assign distinct group rules. At retrieval time, [K-AI MCP](/knowledge-ai/k-ai-mcp/mcp.md) replays the mapped ACL against the calling identity. ## Rate limits & throttling ServiceNow enforces a per-instance rate limit defined by the **inbound REST API rate limit rules** (configurable in the Now Platform — typical defaults: 10 requests/s per user, with burst tolerance). The connector serialises listing calls, paginates through `offset` + `limit` (default page size: 100), and honours `429` responses with exponential back-off and jitter. Attachment downloads are concurrency-capped (default: 4) to avoid breaching the per-user limit when large article batches refresh together. ## Known limitations * **Knowledge Articles only** — Catalog Items, Incidents, and other table content are not ingested by this connector. Use the [Generic HTTP](/knowledge-ai/sources-and-ingestion/connectors/generic-http.md) driver for custom Now Platform tables. * **HTML body extraction** — embedded macros, references to internal Now Platform variables, and dynamic content are rendered as static HTML at ingest time. K-AI does not re-evaluate Now Platform scripts. * **No native ACL** — user-criteria evaluation is not replicated by the connector; access control on the K-AI side is group-rule based. * **Basic auth only** in the current connector. OAuth 2.0 requires the alternative driver. * **Versioned articles** — only the current published version is ingested. Article history is not exposed. * **Translations** — multi-language articles are ingested as separate documents, one per `language` field value. ## Setup walkthrough 1. **Create a ServiceNow service account** in the customer's ServiceNow instance. Assign it the `snc_internal` and `knowledge` roles, and add it to any user criteria that gates the target Knowledge Base. 2. **Identify the Knowledge Base `sys_id`** — open the KB record in `https://{domain}/nav_to.do?uri=kb_knowledge_base_list.do`, right-click the KB → Copy `sys_id`. 3. **Verify access from a curl prompt**: ``` curl -u kai_svc:'' \ 'https://{domain}/api/sn_km_api/knowledge/articles?kb=&limit=1&fields=sys_updated_on' ``` Expect a `200` with a non-empty `result` array. 4. **Add the source in the K-AI admin portal**: select ServiceNow, fill `domain`, `user`, `password`, `db`. Set the sync schedule (e.g. `*/30 * * * *`). 5. **Assign a group rule** for ACL mapping — every article ingested from this KB will inherit that group on the K-AI side. 6. **Trigger a test sync** and confirm the document count via the [Documents endpoint](/knowledge-ai/sources-and-ingestion/instance-api/documents.md) of the K-AI Instance. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/connectors/servicenow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.