ServiceNow

Overview

This integration syncs Knowledge Articles from a ServiceNow Knowledge Base into Leena AI's Knowledge Management (KM) module, enabling the virtual assistant to surface ServiceNow content in employee responses.

At a glance:

• What is synced. Published knowledge articles, and their attachments, from the knowledge bases selected during setup.
• What controls visibility. Optionally, each article's ServiceNow access rules — User Criteria and the roles applied directly on the article — are resolved and mirrored onto the KM article as an audience. Refer to Sync scope and supported permissions.
• Scripted (advanced) User Criteria. Supported, where the ServiceNow instance exposes a Scripted REST resource that Leena AI can call to evaluate them. Refer to Scripted (advanced) User Criteria.
• What is not synced. Articles in any state other than Published.
• How the connection is made. OAuth Client Credentials, using a dedicated ServiceNow service account.

---

Before you begin

The following are required:

• Administrator access to ServiceNow, to register an OAuth application under System OAuth → Application Registry and to configure a service account.
• A dedicated service account holding the roles listed under Service account requirements. A dedicated account, rather than a personal administrator login, keeps the integration stable across staff changes and simple to audit.
• The ServiceNow instance URL, for example https://<instance>.service-now.com.
• Access to the KM dashboard, with permission to configure connectors under Settings → Integrations.
• Where the instance uses scripted (advanced) User Criteria, a Scripted REST resource deployed inside the ServiceNow instance, and a ServiceNow developer able to deploy it. Leena AI cannot install code into a customer's ServiceNow. Refer to Scripted (advanced) User Criteria.

Decide during setup whether ServiceNow access controls should be mirrored into KM. If they should, enable permission sync at configuration time and confirm the service account holds the user and criteria roles. Refer to Sync scope and supported permissions.

---

Service Account Requirements & Permissions

Create a dedicated service account in ServiceNow for this integration rather than reusing an existing user account. Using a dedicated service account ensures that the integration remains stable and is not affected by changes to individual user accounts (e.g., password resets, role changes, or account deactivation).

Once the service account is created, assign it the required roles. Go to User Administration → Users, select your service account user, and ensure all of the following roles are set:

Least-privilege method (custom read-only role)

Where your security policy does not permit the snc_internal role, the service account can instead be given a custom read-only role that only reaches the tables the connector reads. The connector only reads from ServiceNow; it never creates, updates or deletes records. This method gives the connector the same capabilities as the roles listed above.

Step 1: Create the custom role

1. Go to System Security → Roles and click New.
2. Enter a name such as x_leena_km_reader.
3. Leave Elevated privilege unchecked and add nothing under Contains Roles.
4. Click Submit.

Step 2: Assign roles to the service account

Open the service account under User Administration → Users, click Edit in the Roles related list, and add the following roles. Do not add snc_internal, and do not add the account to any group.

Step 3: Elevate to security_admin

Click your name in the banner, choose Elevate role, tick security_admin and confirm.

Step 4: Create two read rules for each table

Each table needs two read rules for the custom role: a table-level rule (<table>) and a field-level rule (<table>.*). Without the field-level rule, records are returned with blank fields.

For each table below:

1. Go to System Security → Access Control (ACL) and click New.
2. Set Type to record and Operation to read.
3. Under Name, select the table in the first dropdown and leave the second dropdown at --None--.
4. In the Requires role list at the bottom of the form, insert a new row, select x_leena_km_reader, and click Insert and Stay.
5. Change only the second Name dropdown to * and click Insert and Stay again. This creates the field-level rule.

Do not modify or deactivate any existing rule.

Knowledge template tables such as kb_template_how_to, kb_template_faq, kb_template_what_is, kb_template_kcs_article, kb_template_known_error_article, kb_knowledge_block, and any custom u_kb_template_* tables extend kb_knowledge and inherit its rules. Add rules for them only if the instance has its own restrictions on those tables.

Step 5: Conditional items

• Scripted (advanced) User Criteria. If the instance uses them, deploy the Leena AI Scripted REST resource (user_criteria_v2) and allow x_leena_km_reader in the resource's access rule.
• Attachment downloads. If attachment file downloads fail with the custom role, add both read rules for sys_attachment_doc.

Step 6: Verify the setup

Impersonate the service account via your name → Impersonate User and confirm that these lists return rows:

• kb_knowledge
• user_criteria
• sys_user_grmember
• sys_attachment
• sys_user, filtered to Company is not empty

If impersonation is blocked for web-service-only accounts on your release, untick Web service access only for the duration of the check, then tick it again.

After the connector is configured, run one test sync and compare three things against ServiceNow: the article count per knowledge base, the attachment count, and the audience for a few restricted articles.

Once your service account is created and the roles are assigned, proceed to the OAuth setup below.

Granting ServiceNow Access Using OAuth

1. Login to your ServiceNow account with your Service Account credentials.

2. Go to your ServiceNow developer instance and select "Application Registry" under "System OAuth".

   

3. Click on "New" application and select the following option: "New Inbound Integration Experience".

   

4. Select New Integrations

5. Select OAuth-Client credentials grant

   

6. Fill in the details about the new app. Select 'useraccount' under Auth scope.

   

7. Please note the Client ID and Client Secret from this step.

---

Leena AI Configuration

1. Go to KM Dashboard >> Settings >> Integrations >> ServiceNow.

2. Fill in the required details:

   • Client ID
   • Client Secret
   • Instance URL

3. Select the setting to move fetched articles to Published state in KM or Draft state.

4. (Optional) Select the option to fetch permissions for ServiceNow.

   

5. (Optional) Where the instance uses scripted (advanced) User Criteria, provide the User Criteria API path — the resource path of the Scripted REST resource deployed in ServiceNow, for example api/x_leena/leena_ai/user_criteria_v2. This is set per connection, so a bot with two ServiceNow connections on different instances carries a separate path for each. Refer to Scripted (advanced) User Criteria.

Syncing

Once the connection succeeds, knowledge articles can be synced from ServiceNow into KM.

All available knowledge bases are listed, and specific knowledge bases can be selected for sync; it is not necessary to sync every knowledge base. After the first full sync, subsequent syncs pick up new, updated, and newly published articles, together with permission changes. Sync cadence is configurable, and more than one ServiceNow connector instance may be run against the same bot — refer to Managing Multiple Instances of a Connector.

Only articles in the Published state are synced. Attribute-based article audiences are resolved by the connector directly; scripted (advanced) User Criteria are resolved by asking ServiceNow to evaluate them, which requires additional setup in the instance. Refer to Sync scope and supported permissions below for the full detail.

The outcome of each run, including skipped and failed articles, is available in the sync logs. Refer to KM Sync Logs and Debugging KM Sync Logs.

---

Sync scope and supported permissions

Which articles are synced

Only articles in the Published state in ServiceNow are synced to Leena KM. Articles in any other state — for example Expired, Draft, or Retired — are excluded, and do not appear in KM even when they belong to a selected knowledge base. To bring an excluded article in, republish it in ServiceNow; it is picked up on the next sync.

Where an article filter has been configured on the connector, it narrows this set further. The knowledge base selection, the Published-state rule, and the article filter apply together.

Including the ServiceNow KB number in article titles

If your users search for articles by their ServiceNow KB number, Leena AI can append the article number to the title of every article it syncs from ServiceNow.

When enabled, a synced article's title becomes: <ServiceNow article title> - KB0012345

This makes the KB number searchable, because it becomes part of the article title that Knowledge Management indexes.

Behaviour

• Applies to knowledge articles only. Attachments keep their original filename as the title.
• Articles with no article number in ServiceNow are unchanged.
• The article title in ServiceNow itself is never modified. Only the title Leena AI stores is affected.
• Turning the setting on or off changes titles from the next sync onward. Titles are never double-appended.

Article filter: supported columns and conditions

A connector may be given an article filter that narrows the sync set beyond the Published-state rule and the knowledge base selection. The filter is expressed as one or more conditions on columns of the kb_knowledge table, and every article that passes the filter is synced.

Columns available for filtering

Only custom columns on kb_knowledge are surfaced as filterable. A column qualifies where its technical name begins with u_, it belongs to a base package (Global), and it was not created by the ServiceNow platform itself. Standard out-of-the-box columns — for example short_description, kb_category, or workflow_state — are not offered as filter columns. In addition to the custom columns, a built-in Valid To filter (backed by valid_to) is always available.

Supported column types and their conditions

A custom column is only surfaced where its ServiceNow internal type is one of the following. Columns of any other type — including Choice and reference (sys_id) columns — are not currently offered as filter columns; where an audience needs to be expressed on such a column, refer to Scripted (advanced) User Criteria or contact the Leena AI CSM.

Between takes a pair of values, inclusive on both ends.

How the filter combines with other rules

The article filter applies alongside — not instead of — the knowledge base selection and the Published-state rule. An article is synced only where it satisfies all three. Where permission sync is also enabled, the audience rules described below are applied after the filter has decided which articles to sync.

What permission sync does

Permission sync controls who can see a synced article in KM.

• When permission sync is disabled, no ServiceNow access rules are read. Each synced article is published to KM without a restricting audience, and is therefore visible to everyone the assistant serves. This is expected behaviour, and it is the most common reason an article's audience appears larger than intended.
• When permission sync is enabled, the connector resolves the set of users permitted to read each article in ServiceNow, and attaches that set as the KM article's audience.

How access is resolved

When permission sync is enabled, an article's KM audience is the set of users who satisfy all applicable ServiceNow read rules. The rules are applied together, so the resulting audience is the most restrictive combination of them:

1. Can Read and Cannot Read User Criteria on the article.
2. Can Read and Cannot Read User Criteria inherited from the parent knowledge base.
3. Roles applied directly on the article, independent of any User Criteria.
4. The article author, who always retains access.

Members of an attribute-based criterion — whether the criterion targets a role, a group, a department, a location, or a company — are fully expanded to the matching users. Scripted criteria are evaluated per user by ServiceNow itself; refer to Scripted (advanced) User Criteria.

1. User criteria

The type of User Criteria configured in ServiceNow determines how its audience is resolved:

• Attribute-based User Criteria are resolved by the connector directly. Criteria that target a role, group, department, location, company, or similar attribute are read from the criterion record, and every matching user is granted or denied read access accordingly.
• Scripted (advanced) User Criteria are resolved by asking ServiceNow to evaluate the script, one user at a time. This requires a Scripted REST resource deployed inside the ServiceNow instance, and the capability to be enabled for the bot. Refer to Scripted (advanced) User Criteria for how this works and how to set it up.

2. Roles applied directly on the article

ServiceNow also permits an article to be restricted to holders of one or more roles by setting the article's Roles field directly, separately from any User Criteria. A common example is restricting an article to users holding the itil role.

The connector reads these directly applied roles, resolves them to the users who hold them, and narrows the article's audience accordingly. A user must therefore both be permitted by the article and knowledge base criteria and hold a required role in order to receive read access. In practice this produces a smaller, more precise audience than the criteria alone would.

Points to note:

• A role of public is treated as "all users" and applies no restriction, consistent with ServiceNow behaviour.
• Where a required role currently resolves to no users — for example, a role that exists but is presently assigned to nobody — the article's audience is reduced to the author only. The article is not released to a broader audience.
• Roles referenced inside a User Criterion have always been honoured. This capability additionally covers roles applied directly on the article.
• This capability is enabled per environment. Where articles are restricted by a role placed directly on the article and their KM audiences appear larger than expected, contact the Leena AI CSM to confirm it is active for the bot, and then re-sync.

Scripted (advanced) User Criteria

A ServiceNow User Criterion answers a single question: can this person see this article? Most criteria answer it declaratively, with a list of groups, roles or departments, and the connector can read that list and work out the audience itself.

An advanced criterion answers it with a server-side script, and its declarative fields are left empty. Previously the connector read those empty fields and concluded that the criterion matched nobody — an answer that looked plausible, and never failed loudly.

The connector now asks ServiceNow to evaluate these criteria properly. Where it cannot obtain an answer, it withholds the article rather than guessing.

Why ServiceNow has to evaluate them

A criterion is not a list of people. It is a test applied to one person at a time. For a declarative criterion the test is stored as data, so the list can be reconstructed. For an advanced criterion the test is arbitrary JavaScript, and nothing in ServiceNow stores who passes it — the platform works it out per user, at the moment someone opens an article.

There is therefore no query for who is in this criterion? The only question the platform can answer is does this specific user pass? That is why a small API has to run inside the ServiceNow instance, and why Leena AI sends it the full user list.

The endpoint the customer deploys

ServiceNow's own evaluator, sn_uc.UserCriteriaLoader, is only callable from inside the instance. A Scripted REST resource exposes it. This resource is customer-deployed — Leena AI cannot install code into a customer's ServiceNow instance.

Leena AI sends one chunk of users, together with the criteria to test:

POST https://<instance>.service-now.com/<user_criteria_api_path>

{
  "users": ["62826bf0…", "7c9f21aa…"],
  "user_criteria": ["a1b2c3d4…"]
}

The endpoint returns one row per user, saying which of the requested criteria that user passed:

{
  "result": [
    {"user": "62826bf0…", "user_criteria": ["a1b2c3d4…"]},
    {"user": "7c9f21aa…", "user_criteria": []},
    {"user": "9de4410b…", "error": "Evaluation failed: …"}
  ]
}

Rules the endpoint must follow

Each of these is enforced. Where a response breaks one, the connector rejects the whole response and withholds the affected articles, rather than building an audience it cannot trust.

Enabling it

Two settings, and the order matters.

1. Connection setting — the User Criteria API path. The resource path after the host, for example api/x_leena/leena_ai/user_criteria_v2. This is set per connection, because one bot can have two ServiceNow connections on different instances. Provide the path to your Leena AI representative, or set it during Leena AI Configuration.
2. Per-bot capability. Advanced criteria evaluation is off by default and is enabled per bot by your Leena AI representative. Raise a request through your usual channel once the endpoint is deployed and the path is set.

With the capability off, nothing changes for that bot — the same behaviour, the same API calls, and the same audiences as before.

Identifying advanced criteria in the instance

The connector treats a criterion as scripted only where advanced = true on the user_criteria record.

A ServiceNow administrator can open the User Criteria list and filter where the Advanced field is true, or query the table directly:

/api/now/table/user_criteria?sysparm_query=advanced=true
  &sysparm_fields=sys_id,name,sys_updated_on

Any records returned are script-based. A criterion that does not appear in this list is treated as declarative, and its declarative fields are read as they stand.

Creating an advanced criterion

Useful when building a test fixture, or when converting an existing rule. Navigation paths shift slightly between ServiceNow releases; if a label does not match, the underlying table is user_criteria.

1. Open User Criteria. Navigate to Knowledge → Administration → User Criteria, then New.

2. Name it, then tick Advanced. Ticking Advanced is what makes the criterion scripted. The declarative fields — User, Group, Role, Company, Location, Department — stop being used, and a Script field becomes the thing that decides.

   Leave the declarative fields empty. If they are filled in and Advanced is ticked, the script still wins, which makes the record confusing to read later.

3. Write the script. It runs for one user at a time and has to resolve to a boolean. A criterion for UK-based staff:

   JavaScript

   (function() {
     var user = gs.getUser();
     answer = user.getRecord().getValue('country') === 'UK';
   })();

   📘

   Verify the convention for your release

   Most instances expect the script to assign answer. Some expect a returned value. Check one of the criteria HRSD ships out of the box and copy its shape.

4. Attach it to a knowledge base or an article. There are two attach points, and they behave differently when something goes wrong:

   • KB level — open the knowledge base record → Can Read / Cannot Read. Applies to every article in it.
   • Article level — open the article → Can Read / Cannot Read. Applies to that article only.

5. Confirm it registered as advanced. Check that the new criterion appears in the advanced=true query above. If it does not, the connector treats it as declarative and reads its (empty) fields.

Alternative: mirror the audience to a group

Where a Scripted REST resource cannot be deployed — for example, where the instance is locked down, or where the change would need a release cycle Leena AI's timeline cannot wait for — a scripted audience can instead be expressed as a user group whose membership is kept current by a scheduled job in ServiceNow. Once the audience is a group, it is attribute-based from KM's perspective and syncs like any other group-based criterion, with no advanced-criteria capability required.

For each scripted User Criterion whose audience should appear in KM:

1. Create a user group in ServiceNow to represent the audience.
2. Add a scheduled job that runs on a regular cadence and updates the group's membership using the same logic the criterion script applies, adding users who now qualify and removing those who no longer do. ServiceNow's scheduled script execution is well suited to this, and the logic mirrors the existing criterion script.
3. On the affected articles, or on their knowledge base, add a Can Read User Criterion that targets the new group, in place of the scripted criterion.

Choosing a refresh cadence. Because group membership is refreshed on the job's schedule rather than evaluated live at each access, the job frequency should match how quickly the underlying attribute changes. For audiences that change infrequently, such as manager level or department, a daily or twice-daily run is usually sufficient. For faster-moving attributes, schedule the job more frequently.

Note that this approach replaces the scripted criterion rather than sitting alongside it. Leaving the scripted criterion attached while the capability is enabled means it is still evaluated, and still withholds articles if it cannot be.

ServiceNow properties that affect resolution

Two ServiceNow knowledge properties influence how access is resolved. The connector honours both, so that KM visibility matches ServiceNow:

How changes propagate

Audiences are recomputed on sync, not in real time:

• Criteria and group changes. Changes to User Criteria, to the criteria attached to a knowledge base, and to group membership are re-evaluated on the next sync, and the audience is updated in KM.
• Role membership changes. Where a user is granted or removed from a role in ServiceNow, articles restricted by that role are re-evaluated on the next sync, provided the article-level roles capability is enabled for the bot. Where it is not enabled, a role membership change alone may not trigger a re-scan until the article is otherwise updated.
• Scripted criteria. Evaluated afresh on each sync by calling the endpoint, so a change to a criterion's script takes effect on the next sync with no change required on the Leena AI side. Where the endpoint is unreachable, or returns a response that breaks the contract above, the affected articles are withheld until a subsequent sync succeeds.
• Toggling permission sync. Enabling or disabling permission sync forces a re-resolution of every existing article on the next sync, so that audiences are brought fully into line with the new setting. Setting the User Criteria API path has the same effect.

Verifying and troubleshooting audiences

• Confirm the setting. Where audiences appear far larger than intended, first confirm that Fetch permissions is enabled on the connector. While it is disabled, every synced article is visible to everyone.
• Re-sync after changes. Audiences update on sync. After changing criteria, group membership, or role assignments in ServiceNow, trigger a sync, or wait for the next scheduled run, before comparing.
• Inspect a specific article. Open the article in KM and review its associated audience, which lists the resolved users. Cross-check this against the users who hold the role, or who match the criterion, in ServiceNow.
• Use the reports and logs. Audience Reports in KM and KM Sync Logs help trace how an article's audience was built, and identify articles that were skipped.
• Where an audience is smaller than expected, check for a Cannot Read criterion that excludes users, or an article role that currently resolves to few or no holders.
• Where articles are missing entirely after enabling advanced criteria, an advanced criterion could not be evaluated and the affected articles were withheld. Confirm the endpoint path is set, that the endpoint is reachable, and that its responses satisfy the rules above. If a whole knowledge base is missing, look for an advanced criterion attached at knowledge base level.

---

Troubleshooting

Connector failures surface a reason in the KM dashboard. Refer to Visibility of Reason for Failure of Connectors and Debugging KM Sync Logs.

---

FAQs

General and authentication

Q: What is the purpose of the ServiceNow integration?
A: It connects a ServiceNow Knowledge Base to Leena AI's Knowledge Management dashboard, so that ServiceNow knowledge articles are synced into KM and can be surfaced by the virtual assistant.

Q: Which connection method is used?
A: OAuth Client Credentials, using a dedicated ServiceNow service account. It is non-interactive, requires neither a refresh token nor a stored service-account password, and is unaffected by the ServiceNow ROPC deprecation.

Q: What is changing with authentication?
A: ServiceNow is deprecating the Resource Owner Password Credentials (ROPC) grant. Connections created earlier using the Token Based (refresh token) or Password Based methods rely on that grant, and continue to work only for as long as the instance still permits it. Those connections must be migrated to Client Credentials. Refer to the advisory at the top of this page.

Configuration

Q: How is a Client ID and Client Secret obtained?
A: In ServiceNow, go to System OAuth → Application Registry and register a new application. ServiceNow generates the Client ID and Client Secret.

Q: What details are required for setup?
A: Client ID, Client Secret, and Instance URL. No refresh token and no service-account password are required. Where the instance uses scripted (advanced) User Criteria, the User Criteria API path is also required.

Syncing

Q: Is it necessary to sync every knowledge base?
A: No. All available knowledge bases are listed, and specific ones can be selected for sync.

Q: Which article statuses are synced from ServiceNow?
A: Only articles in the Published state are synced. Articles that are Expired, Draft, or otherwise not Published are excluded and do not appear in KM. Republishing an article in ServiceNow makes it eligible for the next sync.

Q: What happens to articles after they are synced?
A: Fetched articles can be configured to arrive in KM either in a directly published state or in a draft state.

Q: Are attachments synced?
A: Yes, where Download attachments is enabled on the connector. Attachments on published articles are read from ServiceNow and inherit the parent article's audience. No additional OAuth scope is required: the useraccount auth scope selected during application registration grants the application the access available to the service account, provided Limit authorization to the following APIs is left empty.

Permissions

Q: Can the permissions on ServiceNow articles be synced?
A: Yes. Enable Fetch permissions on the connector. The connector then honours the article's Can Read and Cannot Read User Criteria, the criteria inherited from the knowledge base, any roles or groups referenced inside those criteria, and any roles applied directly on the article. Each KM article's audience is built from the resolved users.

Q: Are scripted (advanced) User Criteria supported?
A: Yes. The connector resolves them by asking ServiceNow to evaluate the criterion for each user. This requires a Scripted REST resource to be deployed inside the ServiceNow instance, the resource path to be configured on the connection, and the capability to be enabled for the bot. Refer to Scripted (advanced) User Criteria.

Q: Why does the customer have to deploy anything? Why can Leena AI not just read the criterion?
A: A declarative criterion stores its test as data, so the audience can be reconstructed from the record. An advanced criterion's test is arbitrary JavaScript, and ServiceNow never stores who passes it — the platform evaluates it per user at the moment of access. There is therefore no query for who is in this criterion?, only does this specific user pass?. ServiceNow's evaluator is callable only from inside the instance, and Leena AI cannot install code into a customer's ServiceNow, so the wrapper has to be customer-deployed.

Q: What happens if the endpoint fails or is unreachable?
A: The affected articles are withheld. Permission sync fails closed: where access cannot be established, an article is not released to a guessed audience. The articles reappear on the first sync that resolves successfully.

Q: Where an advanced criterion is attached at knowledge base level and cannot be evaluated, what is affected?
A: Every article in that knowledge base, not a single article. This matters most on HRSD instances, where HR Criteria are wrapped as advanced criteria by default and an instance can carry several hundred without anyone having authored one. Audit the instance before enabling the capability.

Q: What changes for bots that do not enable the capability?
A: Nothing. The same behaviour, the same API calls, and the same audiences as before.

Q: An article is restricted to a specific role in ServiceNow, but its KM audience appears larger than expected. What should be checked?
A: First confirm that Fetch permissions is enabled; while it is disabled, synced articles are visible to everyone. Where the restriction is a role placed directly on the article, confirm with the Leena AI CSM that the article-level roles capability is active for the bot, and then re-sync. Audiences are recomputed on every sync.

Q: Why does the audience show a list of users rather than the role or criterion name?
A: Leena AI resolves ServiceNow access into the concrete set of users who have access, and builds the audience from that set. The criterion or role definition itself is not copied into KM. Seeing resolved users — derived from the article roles, the User Criteria, and the knowledge base rules — is expected.

Q: How do role and criteria changes in ServiceNow reach KM?
A: On sync. Criteria and group membership changes are re-evaluated on each sync. Role membership changes are re-evaluated where the article-level roles capability is enabled. Scripted criteria are re-evaluated on each sync through the endpoint. Enabling or disabling permission sync, or setting the User Criteria API path, re-resolves every existing article on the next sync.

Q: How can it be determined whether the instance uses scripted User Criteria?
A: A ServiceNow administrator can open the User Criteria list and filter where the Advanced field is true, or query /api/now/table/user_criteria?sysparm_query=advanced=true. Any records returned are script-based.