ServiceNow CSM

Connect ServiceNow Customer Service Management to Squid to search, create, and manage cases

The ServiceNow CSM connector's functionality

The ServiceNow CSM connector enables Squid AI agents to work with Customer Service Management cases on the user's behalf:

Capability	Description
Search cases	Text search of cases by short description, description, or case number, optionally filtered by state
Get case details	Full case details including caller, assignee, comments, and work notes
Semantic search	Natural-language search over indexed cases
Create cases	Create a new case with a short description, description, priority, category, and caller
Reply to cases	Add a public comment or an internal work note to a case

Squid automatically syncs your CSM cases into a knowledge base, refreshing every 10 minutes (the initial sync covers the last year of case history), which enables the semantic search capability.

note

The connector works with ServiceNow Customer Service Management cases (the sn_customerservice_case table). It does not manage ITSM incidents.

Creating a ServiceNow REST API key

The connector authenticates with a ServiceNow API key, sent as an x-sn-apikey header on every request. Setting one up takes four records in ServiceNow, and the key stays inert until all four exist.

Prerequisites

• ServiceNow Washington DC or later. API key authentication does not exist in earlier releases. Check your release at https://YOUR_INSTANCE.service-now.com/stats.do.
• The API Key and HMAC Authentication plugin (com.glide.tokenbased_auth), active under All > Admin Center > Application Manager.
• The Customer Service Management plugin (com.sn_customerservice), which creates the sn_customerservice_case table.

1. Create an integration user

Create a dedicated user under All > User Administration > Users and grant it the sn_customerservice_agent role, plus any additional roles your ACLs require for the case tables. The API key inherits this user's access, so scope the roles to what the connector actually does: read cases, comments, and work notes.

2. Create an inbound authentication profile

1. Navigate to All > System Web Services > API Access Policies > Inbound Authentication Profile.

2. Click New, then Create API Key authentication profiles.

3. Name the profile, for example Squid API Key Profile.

4. In Auth Parameter, select the x-sn-apikey header record.

5. Click Submit.

Warning

Select the header record, not the query parameter record. The connector sends the key only as a header, so a profile wired to a query parameter never matches. An empty Auth Parameter field makes the profile inert and produces 401 responses.

3. Create the REST API key

1. Navigate to All > System Web Services > API Access Policies > REST API Key.

2. Click New, name the key, and set User to the integration user from step 1.

3. Click Submit, then reopen the record and reveal the token.

4. Copy the token. This is the value you will need to paste into Squid.

4. Attach the profile to every policy covering the Table API

ServiceNow evaluates REST API Access Policies by specificity and applies only the single most specific match. Most instances ship with seeded policies that already cover the Table API, so creating a new broad policy usually accomplishes nothing: the seeded policy wins, your policy is never evaluated, and the API key is never consulted.

1. Navigate to All > System Web Services > API Access Policies > REST API Access Policies.

2. Identify every policy that can match a Table API request: any policy with REST API set to Table API, plus any policy with Global checked.

3. On each of those policies, open the Authentication Profiles related list and add the profile from step 2.

4. Leave the existing authentication profiles in place.

Note

A policy permits only the authentication methods attached to it. Removing Basic Auth or OAuth from a policy disables those methods for the entire API.

Adding the ServiceNow CSM connector to your Squid application

1. Navigate to the Connectors tab in the Squid Console.

2. Click Available Connectors.

3. Find the ServiceNow - CSM connector, and select Add Connector.

4. Provide the following configuration details:

Connector ID: A string that uniquely identifies the connector in your code.

Instance Domain: The subdomain of your ServiceNow instance. For example, if your instance is at https://mycompany.service-now.com, enter mycompany.

REST API Token: The API key token created above. The token is stored securely as a Squid secret.

Using the ServiceNow CSM connector in your application

No-code Studio

1. Navigate to the Studio tab in the Squid Console.

2. Click Create AI Agent.

3. Provide an agent ID and description, such as "csm-agent" and "This agent helps the user manage ServiceNow customer service cases".

4. Click Add Abilities.

5. Expand the ServiceNow - CSM entry and select the connector you created earlier.

6. Give a description for how the agent should use this connection, such as "Call this when a user wants to manage cases or customer service tasks in ServiceNow CSM."

7. Click on Test and try asking the agent "What are the open cases?".

Using the Squid SDK

If you are creating your AI agent with the Squid SDK, connect the connector by adding it to the connectedIntegrations option of the ask() function:

TypeScript

await this.squid
  .ai()
  .agent('AGENT_ID')
  .ask('Summarize the most recent customer cases about billing', {
    connectedIntegrations: [
      {
        integrationId: 'SERVICENOW_CONNECTOR_ID',
        integrationType: 'servicenow_csm',
        description: 'Call this connector to manage ServiceNow CSM cases',
      },
    ],
  });

Python

await squid.ai().agent('AGENT_ID').ask(
    'Summarize the most recent customer cases about billing',
    options={
        'connectedIntegrations': [
            {
                'integrationId': 'SERVICENOW_CONNECTOR_ID',
                'integrationType': 'servicenow_csm',
                'description': 'Call this connector to manage ServiceNow CSM cases',
            }
        ]
    },
)

Using the npm package

For programmatic (non-agent) access from your backend or client code, install the @squidcloud/servicenow_csm-client package:

npm install @squidcloud/servicenow_csm-client

import { SquidServiceNowCSMClient } from '@squidcloud/servicenow_csm-client';

const servicenow = new SquidServiceNowCSMClient(squid, 'SERVICENOW_CONNECTOR_ID');

// Search and inspect cases
const cases = await servicenow.searchCases('billing');
const details = await servicenow.getCase(cases[0].number);

// Create a case and reply to it
const created = await servicenow.createCase({ shortDescription: 'Billing discrepancy' });
await servicenow.replyToCase(created.number, 'We are investigating.', true);

note

ServiceNow uses numeric codes for priority (1 = Critical through 5 = Planning) and case state (1 = New, 2 = In Progress, 3 = On Hold, 6 = Resolved, 7 = Closed, 8 = Canceled).