# ServiceNow URL: https://docs.clearly-ai.com/docs/integrations/issue-trackers/service-now Description: Connect Clearly AI to ServiceNow. ## Capabilities [#capabilities] ### Chat [#chat] Clearly AI uses these tools to ground chats with ServiceNow data. | Tool | Behavior | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_tasks` | LIKE match on `description` and `short_description` across `task`, and therefore every child table, with one clause per term OR'd together, plus an exact match on number-shaped terms. Returns at most 100 results. Also feeds Clearly AI unified search. | | `search_knowledge` | `sn_km_api` search, which follows the Knowledge Base's own publish and visibility rules. Returns at most 100 results. | | `read_record` / `load` | A full record as markdown. Subject to the number-prefix limit. | | `read_knowledge` | A full article by `sys_id`. | | `list_tasks_by_assignee` | Tasks where `assigned_to` is the asking user, matched by their Clearly AI email, and `active=true`, newest first, capped at 25. Answers "what's on my plate". | The most common tables are child tables of `task`, such as `incident`, `problem`, `sc_request`, `sc_req_item`, and `sc_task`. ### Sources [#sources] Anywhere in Clearly AI, paste a link to a ServiceNow record (a task, a child table of task, or a knowledge article) and Clearly AI fetches the content. This works when you add a project source. Clearly AI also fetches ServiceNow records linked from a document it is processing. ### Automation [#automation] Clearly AI can trigger on any ServiceNow event, such as an RITM for a "New Vendor" or a high-risk change entering "Assess". You set up each automation as a business rule in ServiceNow. ### Write [#write] Clearly AI can issue four actions in ServiceNow as part of a workflow. | Operation | Call | | ------------- | ------------------------------------------------------------------------------------------------------------------------- | | Create record | `POST /table/{table}` for any table you choose. Sets `short_description`, `description`, and any other fields you pass. | | Comment | `PATCH /table/{class}/{sys_id}` with `{"comments": ...}`. This is a customer-visible Additional comment, not a work note. | | Assign | `PATCH` with `{"assigned_to": }`. The ServiceNow user is found by matching the Clearly AI user's email. | | Attach file | `POST /attachment/file?table_name=&table_sys_id=&file_name=` | *** ## Connection [#connection] Clearly AI connects to ServiceNow using the OAuth 2.0 client credentials grant. In Clearly AI, the ServiceNow credentials are stored as a workspace-level secret and used for integrations across that entire Clearly AI workspace. For this reason, the OAuth client in ServiceNow should be configured on behalf of a dedicated ServiceNow system account (service principal) rather than an individual employee account. The access token issued by ServiceNow represents the OAuth application user you configure, and ServiceNow enforces table/field ACLs for that user on every REST API request. ### Custom tables [#custom-tables] **Record tables** is an optional setting on the ServiceNow connection. It lists custom tables that Clearly AI reads records from, such as `x_acme_security_review`. Clearly AI checks those tables first when it looks up a record by sys\_id or number. It can read the record, add comments, and attach files. Clearly AI shows every field on the record. Reference fields show the display name and sys\_id. The service account needs read access to each configured table and write access to its `comments` field. It also needs read and create access to `sys_attachment` for records in that table. **Test connection** reads one record from each table listed in **Record tables**. See the Appendix for guidance on permissions, least-privilege principle, and supported modules. *** ## Instructions [#instructions] ### Prerequisites [#prerequisites] You will need to be an administrator of your ServiceNow instance to complete all steps.\ The OAuth plugin is typically active by default on new and upgraded ServiceNow instances, but it can be inactive in some environments. 1. Activate the OAuth 2.0 plugin. Instructions: [https://www.servicenow.com/docs/bundle/zurich-platform-security/page/administer/security/task/t\_ActivateOAuth.html](https://www.servicenow.com/docs/bundle/zurich-platform-security/page/administer/security/task/t_ActivateOAuth.html) 2. Set the OAuth property (`com.snc.platform.security.oauth.is.active`) to **true**. Instructions: [https://www.servicenow.com/docs/bundle/zurich-platform-security/page/administer/security/task/t\_SetTheOAuthProperty.html](https://www.servicenow.com/docs/bundle/zurich-platform-security/page/administer/security/task/t_SetTheOAuthProperty.html) ### Create a Service Account for Clearly AI [#create-a-service-account-for-clearly-ai] Create or designate a dedicated ServiceNow service account that will represent Clearly AI (for example, `clearly_ai_integration`), and assign only the roles and permissions required for the data you intend Clearly AI to access. All API access in the client-credentials flow is evaluated as this user. ### Enable Client Credentials [#enable-client-credentials] To use the client credentials grant type, you must perform the following steps: 1. Create the `glide.oauth.inbound.client.credential.grant_type.enabled` system property and set it to `true`: [https://www.servicenow.com/docs/bundle/zurich-platform-security/page/integrate/authentication/concept/client-credentials.html](https://www.servicenow.com/docs/bundle/zurich-platform-security/page/integrate/authentication/concept/client-credentials.html) 2. Add the OAuth Application User field to the OAuth Entity form if it is not already visible: [https://www.servicenow.com/docs/bundle/zurich-platform-security/page/integrate/authentication/task/add-oauth-application-user.html](https://www.servicenow.com/docs/bundle/zurich-platform-security/page/integrate/authentication/task/add-oauth-application-user.html) ### Create an OAuth API Endpoint for External Clients [#create-an-oauth-api-endpoint-for-external-clients] Create an OAuth API Endpoint configured for Client Credentials in the Application Registry. Instructions: [https://www.servicenow.com/docs/bundle/zurich-platform-security/page/administer/security/task/t\_CreateEndpointforExternalClients.html](https://www.servicenow.com/docs/bundle/zurich-platform-security/page/administer/security/task/t_CreateEndpointforExternalClients.html) 1. Navigate to **All → System OAuth → Application Registry** 2. Click **New** and select **Create an OAuth API endpoint for external clients**. 3. Complete the form and save. ServiceNow will generate a **Client ID** and **Client Secret** for this client. 4. In the OAuth client record you created, set the default grant type to **Client Credentials** and set **OAuth Application User** to the service principal from step 1. This ensures tokens are issued with that user's permissions. ### Enter credentials in Clearly AI [#enter-credentials-in-clearly-ai] 1. In Clearly AI, open **Organization settings**, select **Integrations**, then click **Set up** on the ServiceNow card. Provide: * Your ServiceNow instance URL (for example, `https://yourinstance.service-now.com`) * Client ID * Client Secret * Optional: under **Record tables**, the custom tables Clearly AI should read records from (see [Custom tables](#custom-tables)) 2. Check **I understand** under the shared-credential notice, then click **Add workspace credential**. Clearly AI tests the credential and enables the integration only when the test passes. You can't view the stored secret after it's saved. *** ## Configure ServiceNow webhooks for Workflows [#configure-servicenow-webhooks-for-workflows] Configure a webhook when a ServiceNow record create or update should start a Clearly AI workflow in real time. Keep the OAuth connection above if Clearly AI also needs to read the record after the webhook arrives. ### Generate the Clearly AI webhook secret [#generate-the-clearly-ai-webhook-secret] 1. In Clearly AI, open **Organization settings**, select **Integrations**, click **Configure** on the ServiceNow card, open the **Webhooks** tab, and click **Edit webhook**. 2. Click **Generate new secret** next to **Secret**, and enter the ServiceNow instance name in **Instance Name** (for example `dev123456`). 3. Click **Apply and Test**. 4. Click **Edit webhook** again and copy the **Webhook URL**. The path is `/api/webhook/servicenow` on your Clearly AI instance. ### Create a Clearly AI workflow [#create-a-clearly-ai-workflow] 1. Go to **Workflows** → **Create Workflow** → **Create from scratch**. 2. Add a **ServiceNow Record Created or Updated** trigger and choose the tables to listen on (for example `incident`, `change_request`, `sc_task`). 3. Add a **Create Project** node. In **Title**, type `@` to insert fields from the ServiceNow record. Set a submitter. 4. Save and enable the workflow. ### Create a ServiceNow Business Rule [#create-a-servicenow-business-rule] You need ServiceNow admin access to create Business Rules. 1. In ServiceNow, go to **All → System Definition → Business Rules → New**. 2. Name it (for example `Clearly AI Webhook`), pick the table, and enable **Advanced**. 3. Under **When to run**, use **async** on **insert** and/or **update** as needed. 4. In **Advanced**, paste this script and replace the placeholders: ```javascript (function executeRule(current, previous /* null when async */) { try { var r = new sn_ws.RESTMessageV2(); r.setEndpoint('/api/webhook/servicenow'); r.setHttpMethod('post'); r.setRequestHeader('Content-Type', 'application/json'); r.setRequestHeader('X-Clearly-Webhook-Secret', ''); r.setRequestBody(JSON.stringify({ sys_id: current.getUniqueValue(), number: current.getValue('number'), short_description: current.getValue('short_description'), table: current.getValue('sys_class_name'), requested_for: current.getValue('requested_for'), requested_by: current.getValue('requested_by'), instance: '' })); var response = r.execute(); gs.info('Clearly AI webhook sent. Status: ' + response.getStatusCode()); } catch (ex) { gs.error('Clearly AI webhook failed: ' + ex.message); } })(current, previous); ``` | Placeholder | Value | | ---------------------------- | -------------------------------------------------------------------- | | `` | Your Clearly AI host, for example `https://your-org.clearly-app.com` | | `` | The secret generated in Clearly AI | | `` | The instance name saved in Clearly AI webhook settings | 5. Save and activate the Business Rule. ### Payload fields [#payload-fields] | Field | Required | Description | | ------------------------------- | ------------------------------------------- | ------------------------------------ | | `sys_id` or `number` | Yes (one of them) | Record identity | | `table` | Yes | Table name, usually `sys_class_name` | | `instance` | Yes unless set in Clearly AI webhook config | ServiceNow instance name | | `short_description` | No | Used as the event name | | `requested_for`, `requested_by` | No | Passed through to the workflow event | ## FAQs [#faqs] Confirm the Business Rule is active, the table matches the Workflow trigger, and ServiceNow system logs show a 2xx response from Clearly AI. The `X-Clearly-Webhook-Secret` header must match the secret saved in Clearly AI. Confirm the webhook URL path is `/api/webhook/servicenow` on your Clearly AI instance. The body must include `table` and either `number` or `sys_id`, plus an instance name in the body or webhook config. *** ## Appendix [#appendix] ### Token endpoint used by Clearly AI [#token-endpoint-used-by-clearly-ai] Clearly AI requests tokens from the standard ServiceNow token endpoint: `https://.service-now.com/oauth_token.do` ### Permissions guidance [#permissions-guidance] If you see successful authentication but no records returned for tables you expect to be readable, validate the service principal’s roles and ACL access for those tables and fields, and confirm that the records you are searching for are visible to that account (for example, in environments with domain separation or restrictive table ACLs). The simplest way to confirm whether this is a permissions issue is to temporarily grant read access in a controlled way and re-test, then roll back to least privilege once the required access pattern is understood. ### Least-privilege guidance [#least-privilege-guidance] Because the integration uses a workspace-level secret and operates under a single service principal, it is important to scope permissions deliberately. Customers typically start by confirming read access to the specific tables they care about (for example, `incident`, `change_request`, `problem`, `sc_req_item`, and `kb_knowledge`), then tighten roles and ACL rules until the service account has only the minimum access needed for the intended Clearly AI workflows. ### Supported modules [#supported-modules] Please keep in mind that availability depends on the modules installed and licensed in your ServiceNow instance and the access controls you set on the OAuth application user’s roles and ACLs. It is normal for some tables to return zero results if the account is not permitted to read them. The Clearly AI ServiceNow connector supports the following ServiceNow modules out of the box. * **IT Service Management** records, including incidents, problems, and change requests, as well as general task records (via the Task table). * **Service Catalog** request records, including requests, requested items, and catalog tasks; the connector can also read requested-item option values where present. * **Knowledge Management** articles, including knowledge search and article retrieval (knowledge availability depends on the relevant API/plugin being enabled in the instance). * **Configuration item references** on records, shown by name and sys\_id. Clearly AI doesn't follow these references to read CMDB records. * **Users** for identity resolution of reference fields. * **Attachments**, including listing attachments for a record and downloading attachment content through the attachment file endpoint. | ServiceNow area | What Clearly AI accesses | Primary tables/endpoints involved | | ------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | IT Service Management (ITSM) | Incidents, Problems, Change Requests, and general task records | `incident`, `problem`, `change_request`, `task` | | Service Catalog | Requests, Requested Items, and Catalog Tasks; reads item option values for requested items | `sc_request`, `sc_req_item`, `sc_task`, `sc_item_option_mtom`, `sc_item_option` | | Knowledge Management | Knowledge articles and knowledge search; may use the specialized KM API when needed | `kb_knowledge`, `/api/sn_km_api/knowledge/articles` | | Configuration item references | Shows a record's reference name and sys\_id; doesn't follow references to read CMDB records | Reference field on the source record | | Users | Resolves user fields and looks up users by sys\_id or username | `sys_user` | | Attachments | Lists and downloads attachments associated with records | `sys_attachment`, `/api/now/attachment/{sys_id}/file` | | Additional modules when present | Some record-number patterns map to additional tables if they exist and are permitted | `rm_task`, `rm_story`, `sn_compliance_policy`, `engagement` | The connector can identify record-number prefixes that map to optional tables. Clearly AI's connection to ServiceNow is built around ServiceNow’s REST APIs: Table API for record retrieval, Attachment API for attachment metadata and file downloads, and Knowledge API for searching and retrieving knowledge articles. These operations enforce that the calling user has sufficient roles to access the requested table data. Contact us if you need additional modules, tables, prefixes, or permission models.