ServiceNow

Overview

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.

See the Appendix for guidance on permissions, least-privilege principle, and supported modules.

Instructions

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
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

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

1. In Clearly AI, open Integrations and select ServiceNow.
2. Expand Webhooks, generate a secret, and enter the ServiceNow instance name (for example dev123456).
3. Click Apply & Test, then save.
4. Copy the webhook URL shown after save. The path is /api/webhook/servicenow on your Clearly AI instance.

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

1. In ServiceNow, go to All → System Definition → Business Rules → New.
2. Name it (for example ClearlyAI 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:

(function executeRule(current, previous /* null when async */) {
    try {
        var r = new sn_ws.RESTMessageV2();
        r.setEndpoint('<CLEARLY_INSTANCE_URL>/api/webhook/servicenow');
        r.setHttpMethod('post');
        r.setRequestHeader('Content-Type', 'application/json');
        r.setRequestHeader('X-Clearly-Webhook-Secret', '<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: '<SERVICENOW_INSTANCE_NAME>'
        }));
        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);

5. Save and activate the Business Rule.

Payload fields

FAQs

Appendix

Token endpoint used by Clearly AI

Clearly AI requests tokens from the standard ServiceNow token endpoint:

https://<your-instance>.service-now.com/oauth_token.do

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

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

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).
• CMDB configuration items.
• Users for identity resolution of reference fields.
• Attachments, including listing attachments for a record and downloading attachment content through the attachment file endpoint.

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.