Introduction

The Servicenow connector allows Simpplr Enterprise Search to index Servicenow Storage content, making it easily discoverable and searchable directly within Simpplr.

With this connector, you can (use cases):

• Bring  Servicenow content into Simpplr Enterprise Search so users can find files alongside intranet content in one place.

• Respect Servicenow access permissions so users only see files they already have access to in Servicenow.

• Use advanced features like autocomplete, hybrid ranking, and Smart Answers on top of Servicenow content.

Indexed content from Simpplr Enterprise Search is available in:

• In main search listing

• Smart answers

Capabilities at a glance

Objects and content supported

1. Objects - 

   1. Knowledge Base Article in published state

      • Articles in other states, such as draft, retired and outdated are not synced

2. Metadata - For each indexed item, Servicenow captures:

   1. Name

   2. URL / link

   3. Created time and Updated Time

   4. Parent Details

   5. Object Type

   6. Permissions (users and groups level access) (See Advanced configuration)

3. Permissions model - Permissions are read from Servicenow and enforced in Simpplr Enterprise Search: 

   1. How user and group permissions are synchronized

      1. ServiceNow user and group memberships are fetched and stored 

      2. When a user is added to or removed from a Servicenow User Criteria , the index is updated the next time the sync runs (by default, every hour).

   2. How public or link-shared content is handled

      1. Content that is only available via anonymous or public shared links is not indexed in the current version.

   3. What happens when access is removed for a specific document

      1. When a user loses access to a file or folder in Servicenow, the updated permissions are applied during the next sync.

      2. The file will no longer appear in that user’s Simpplr search results after the next sync completes.

Versions and editions supported

• Supports enabled Servicenow Service.

Prerequisites

Before you begin, ensure the following: Source system Access - Access to Servicenow Instance with Admin role

Authentication and security

1. Authentication mechanism
   Describe how  Simpplr Enterprise Search connects to Servicenow:

   1. Auth type: Basic Authentication (Client credentials)

2. Data security

   1. Data storage and residency: Indexed content and ACLs from Servicenow are stored within your Simpplr Enterprise Search environment, in the same region as your Simpplr tenant.

   2. Encryption in transit: Server-side encryption with Amazon S3 managed keys (SSE-S3), TLS encryption in Kafka.

   3. Encryption at rest: SSL (TLS 1.2 or higher), Auth: OAuth 2.0 client-credentials.

   4. Permission enforcement: Servicenow access controls (users and groups) are stored in the index and applied at query time. Search results are always filtered by the signed-in user’s identity and Servicenow group memberships.

Setup and configuration

Step 1 - Source Setup in ServiceNow

Step Outcome

• Instance URL: (e.g., [https://ven05143.service-now.com/]

• Custom Service Account Username

• Custom Service Account Password (Please reset the password and verify the credentials are working before use.)

Basic Setup

With basic setup, users with the following roles will be able to access the KB Articles in Simpplr Enterprise Search:

• admin

• knowledge

• knowledge_manager

• knowledge_admin

1. Create a Custom Service Account User

• Create a dedicated custom service account user with user name :  simpplr_enterprise_search.

2. Assign Required Roles

• Ensure the custom service account user is assigned the following two roles:

  • admin

  • snc_read_only (Ensures the access is readonly)

Advanced Setup

Advanced setup is used to sync User Criteria. Requires the setup of a scripted REST API within your ServiceNow instance. We need to create:

• Scripted REST API for fetching User Criteria associated with User

• Scripted REST API for fetching User Criteria associated with Documents

1 - Scripted REST API for fetching User Criteria associated with User

 1. Create the Scripted REST API Service for User Criteria API

• Navigate to System Web Services > Scripted Web Services > Scripted REST APIs

• Click New

• Fill in the following fields:

  • Name: Get User Criteria

  • API ID: Will auto-populate as get_user_criteria_api

  • Active: Checked

• Click Submit

• This will generate a base API path like /api/x_your_scope/get_user_criteria_api

2. Create the Scripted REST API  Script for User Criteria API 

• Open your newly created Scripted REST API record

• In the Resources related list, click New

• Fill in the resource details:

  • Name: Get User Criteria

  • HTTP method: GET

  • Relative path: /user_criteria/{user_id}

  • Active: Checked

• In the Script field, paste the working script provided below

• Under Security section:

  • Check Requires authentication

  • Check Requires ACL authorization

  • Set ACLs to the Scripted Rest External Default

• Click Submit

• Paste the below script : 

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    // Log request entry
    gs.info("User Criteria API: Received request");

    try {
        // FIX: Extract user ID from path parameters instead of query parameters
        var pathParams = request.pathParams;
        gs.info("User Criteria API: Path parameters: " + JSON.stringify(pathParams));
        
        // Extract user_id from path parameter and convert to string
        var userID = pathParams.user_id ? String(pathParams.user_id) : '';
        
        // Log incoming user parameter
        gs.info("User Criteria API: Received user ID: " + userID);

        if (!userID || userID == 'undefined' || userID == '') {
            gs.error("User Criteria API: Missing user_id parameter in request path.");
            response.setStatus(400);
            response.setBody({
                error: "Bad Request",
                message: "User ID is required in the path. Use format: /user_criteria/{user_id}"
            });
            return;
        }

        // Track user criteria loading
        gs.info("User Criteria API: Invoking UserCriteriaLoader for user " + userID);

        var allCriterias = new sn_uc.UserCriteriaLoader().getAllUserCriteria(userID);
        gs.info("User Criteria API: Criteria sys_ids found: " + JSON.stringify(allCriterias));
        gs.info("User Criteria API: Number of criteria matched: " + allCriterias.length);

        var criteriaDetails = [];
        for (var i = 0; i < allCriterias.length; i++) {
            gs.debug("User Criteria API: Processing criteria sys_id: " + allCriterias[i]);
            var ucGR = new GlideRecord('user_criteria');
            if (ucGR.get(allCriterias[i])) {
                // Convert values to plain strings to avoid serialization issues
                criteriaDetails.push({
                    sys_id: String(ucGR.getValue('sys_id')),
                    name: String(ucGR.getValue('name')),
                    active: String(ucGR.getValue('active')),
                    match_all: String(ucGR.getValue('match_all')),
                    advanced: String(ucGR.getValue('advanced'))
                });
                gs.debug("User Criteria API: Added details for criteria: " + ucGR.getValue('name'));
            } else {
                gs.error("User Criteria API: No record found for criteria sys_id: " + allCriterias[i]);
            }
        }

        // Log response composition
        gs.info("User Criteria API: Returning " + criteriaDetails.length + " criteria details");
        
        // Return empty object if no criteria found
        if (criteriaDetails.length === 0) {
            response.setStatus(200);
            response.setBody({});
        } else {
            var responseBody = {
                user_id: String(userID),
                total_criteria: parseInt(criteriaDetails.length, 10),
                user_criteria: criteriaDetails
            };
            
            response.setStatus(200);
            response.setBody(responseBody);
        }

    } catch (error) {
        gs.error("User Criteria API: Error encountered: " + error.message);
        gs.error("User Criteria API: Error stack: " + error.stack);
        response.setStatus(500);
        response.setBody({
            error: "Internal Server Error",
            message: String(error.message)
        });
    }
})(request, response);

Step 2 - Create the connector in Enterprise Application

1. In Simpplr, go to: Manage features → Enterprise search → Add source.

2. Search and Select “ServiceNow”.

3. Enter basic information:

   • Connection Name: (Connector name for this instance)

4. Provide authentication details and select the certificate toggle in authentication method  (Copied from the client Application):

   • Servicenow Instance URL

   • Servicenow Admin Username

   • Servicenow Admin Password

Connector Filters (Optional)

Configure Knowledge Base Filters (Inclusion Only):

You need to provide either the ID or the URL of the desired Knowledge Base from your ServiceNow instance.

Steps to obtain the ID or URL:

1. Search for and navigate to the Knowledge Base listing in ServiceNow.

2. Select the desired Knowledge Base.

3. Click on "Copy sys_id" or "Copy URL to Clipboard" to retrieve the required value.

4. Enter the retrieved sys_id or URL in the configuration.

   1. Configure Audience based filtering.

      • Include audiences

      • Exclude audiences

Monitor the sync

1. Monitor the initial full sync status (starts automatically) in the connector dashboard.

Crawling and sync behavior

How the connector works over time:

1. Initial full crawl

   1. All the content present in the Servicenow Storage account is indexed during the first run

   2. How long it may take: Depends on the size of the content.

2. Incremental updates

   1. Mechanism: Based on Timestamp of previous sync.

   2. What changes trigger reindexing:

      • New items created

      • Existing items updated

      • Permissions changed

      • Items moved or renamed

      • Items deleted or archived

3. Deletion and permission changes

   1. Deleted items are removed from index at next sync.

   2. Permission changes are updated at the next sync cycle.

Field mapping and search experience

1. Default field mapping

Source field Servicenow → Index field Simpplr

2.  Search experience - how content from this connector appears in search:

   1. Result layout: (Icon, Connector name, Folder name, title (name) as link, body(excerpt), Created Date, File Type icon, file type)

   2. Available filters and facets:

      • Sources = Servicenow

      • File type

      • Owner

      • Created Date

3. Participation in advanced features:

   • Smart Answers / Q&A: Yes

   • Autocomplete: Yes

   • Semantic / hybrid ranking: Yes

1. Default field mapping

Source field Servicenow → Index field Simpplr

2.  Search experience - how content from this connector appears in search:

   1. Result layout: (Icon, Connector name, Folder name, title (name) as link, body(excerpt), Created Date, File Type icon, file type)

3. Available filters and facets:

   • Sources = Servicenow

   • File type

   • Owner

   • Created Date

4. Participation in advanced features:

   • Smart Answers / Q&A: Yes

   • Autocomplete: Yes

   • Recommendations / “Suggested for you”: N/A

   • Trending / popular results: N/A

   • Semantic / hybrid ranking: Yes

Known limitations

Monitoring and troubleshooting

Connector health and monitoring

• Enterprise Search → Connector name

• Available metrics:

  • Last sync time

  • Next scheduled sync

  • Sync Type

  • Total items indexed count

Common issues and resolutions

Authentication failed

Failed to fetch the access token (invalid credentials or missing scopes)

Possible causes:

1. Incorrect username or password

2. User Configured is not admin

Resolution:

1. Verify and re-enter credentials

2. Confirm required roles are granted for the service account created 

When to contact support 

1. Authentication error persists even after trying the above-mentioned resolutions

2. Sync is stuck and hasn’t progressed in a few hours,

3. Sync failure

4. Incomplete or Partial sync.

When contacting Support, include:

• Connector name and instance ID (if available)

• Organization URL

• Approximate time and date of the issue

• Error messages or screenshots

• Steps you already tried

Frequently asked questions (FAQ)

Q1. Can I connect multiple Servicenow tenants or domains?
A. Multiple Servicenow connections can be configured in the Simpplr environment.

Q2. How often does Servicenow sync data?
A. The connector runs a full crawl on first setup. Incremental sync runs every 1 hour.

Q3. What happens when a user loses access to an item in Servicenow?
A. The updated access permissions will be indexed during the next sync.

Note: Files and permissions are synced every hour. However, the actual update time may vary depending on the volume of data created within that period. Under normal conditions, changes are reflected within 1–2 hours, provided there has not been a significant spike in data uploads.

Q4. How are deletions handled?
A. Objects deleted from the source are permanently deleted from the ind