Introduction
The ServiceNow connector for Glean allows Glean to fetch and index content from Knowledge Articles, Service Catalog items, ITSM incidents, APM Business Applications and SPM demands, Epics and Projects ensuring that users can search for and access documents for which they have authorized permissions.
Authentication: is done by creating a dedicated user account with specified permissions and profiles
API Usage: Glean will use the Table API and then Scripted REST API for advanced user criteria
Permissions Enforcement: Glean respects all user access permissions, ensuring users only see search results for documents they have access to. When a user clicks on a search result, they are taken to the ServiceNow web application, which enforces the permission
Data Storage: All data is stored in the customer’s project within the customer's cloud account, ensuring no data leaves the customer's environment
Content Captured:
For ServiceNow, Glean will capture the following content:
Knowledge Articles
Service Catalog
With additional permissions and configuration, Glean will capture the following content:
ITSM
APM
SPM
ServiceNow Permissions
Admin access to setup the connector
Admin access for the Service Account is preferred (Custom role can be defined)
Disclaimer: Please be advised that Glean does not recommend utilizing a ServiceNow account associated with an employee. If the employee departs from the company or if the account becomes disabled, it will adversely affect access to data sources.)
Versions Supported
There are no specific version limitations of the ServiceNow connector.
Objects Supported
The ServiceNow connector supports the following objects:
Knowledge articles:
knowledge base
short description
workflow state
created by
description
knowledge base category
view count
custom fields (for knowledge articles created from custom templates)
Catalog items:
title
created by
short description
description
catalog category
sc_catalogs
ITSM:
number
short description
description
comments and work notes
state
priority
impact
urgency
category
assigned to
opened by
Authentication Mechanism
Connector credentials requirements
The Service connector for Glean requires specific permissions to function correctly.
Glean requires authentication by utilizing a dedicated Service Account and OAuth Application
Glean understands all user access permissions and strictly enforces them at the time of the query, ensuring that users cannot see results to which they do not have access.
It’s important to note that all data is stored in the customer’s project in the customer's cloud account, and no data leaves the customer's environment.
Glean only requires READ-level permissions.
Role | Use Case |
knowledge_admin | Required to fetch Knowledge Articles. This role allows us to view all Knowledge Articles and Knowledge Bases in the global instance. |
user_criteria_admin | Required to fetch user criteria.
|
user_admin | Required to fetch ServiceNow users |
catalog_admin | Required to fetch Catalog items |
web_service_admin | Required in advanced setup so that we can access the scripted API |
snc_read_only | Effectively restricts the service account user to readonly |
snc_internal | |
itil | Required to fetch ITSM Incidents |
sn_apm.apm_user | Required to fetch APM Business Applications |
it_project_user | Required for SPM Projects |
it_demand_user | Required for SPM Demands |
scrum_user | Required for SPM Epics |
safe_scrum_user | Required for SPM Epics |
Creating a Service Account in ServiceNow
Create a service account that Glean will use for fetching information from ServiceNow:
Navigate to Organization > Users and click New.
Set User ID to gleansearch
Check Web service access only.
Set the Time zone to GMT. This is required for Glean to pick up new content updates.
Leave the remaining fields as-is. Click Submit.
Click on the gleansearch user that was created.
Click Set Password and choose a strong password (save for connector setup).
Provide access to sys_audit_delete table
Access to the sys_audit_delete table will result in faster updates to document permissions when identity data changes.
Create a new role: read_access_sys_audit_delete:
Navigate to User Administration → Roles.
Click on New and enter the name as
read_access_sys_audit_delete
Click Save.
Add an ACL rule that gives this role read access to the sys_audit_delete table:
Elevate role to security_admin to be able to create a new ACL.
Navigate to System Security → Access Control (ACL).
Click on New and enter the following details.
Type: record
Operation: read
Name: Select the sys_audit_delete table
Add the new read_access_sys_audit_delete role under Requires role
Click Submit.
Assign the new role read_access_sys_audit_delete to gleansearch user.
Configure an OAuth Application
OAuth will provide access tokens to Glean acting as the previously configured user.
Navigate to System OAuth → Application Registry and click New.
Click Create an OAuth API endpoint for external clients.
Set Name to Glean Search OAuth.
Set Refresh Token Lifespan to 2,147,483,647.
Set Access Token Lifespan to 86,400.
Leave the remaining fields as defaults and Click Submit.
Validate System Properties:
Navigate to the System Properties List (All → Enter sys_properties.list).
Identify and note the system property glide.knowman.apply_article_read_criteria and its value.
Identify and note the system property glide.knowman.block_access_with_no_user_criteria and its value.
Identify if there are any Knowledge Article templates enabled and want to index template-based articles.
Navigate to All → System Applications → All Available Applications → All
Search for the plugin Knowledge Management Advanced (com.snc.knowledge_advanced) and check if it is enabled.
To learn more about knowledge article templates here.
Creating a Custom Role in ServiceNow
In cases where admin privileges are unavailable as a ServiceNow user, Glean will be able to recreate the same Glean experience with a user as a custom role. The majority of steps will be the same as listed in the ServiceNow Connector setup instructions, except for the following:
Note: The User fetching on behalf of does not need to be an admin (or have admin privileges). However, an admin (or a user with security_admin privileges) must complete some of the following steps.
Create the user that will be used and name it: gleansearch
Create a custom role named: CustomRole
Click on the user (Organizations → Users) and then set CustomRole for the user gleansearch under Roles
When creating the ACL Rule (System Security → Access Control (ACL)) for the Scripted REST API, then set CustomRole as the role for the ACL Rule.
Set the ACL Rule that requires the CustomRole for both the new Scripted REST API and the /user_criteria endpoint.
In step 2, instead of setting roles for the user, provide read access to the necessary tables (see below). As a security admin, create a new ACL Rule for each table, granting CustomRole the read record access. Provide the read access for all fields of the tablein a separate ACL Rule. Create two ACL Rules for each of the following tables:
sys_user
sys_user_role
sys_user_has_role
sys_user_group
sys_user_grmember
user_criteria
kb_knowledge
kb_knowledge_base
kb_uc_can_read_mtom
kb_uc_cannot_read_mtom
kb_uc_can_contribute_mtom
kb_uc_cannot_contribute_mtom
kb_category
kb_use
sc_cat_item
sc_cat_item_user_criteria_mtom
sc_cat_item_user_criteria_no_mtom
sc_category
sc_catalog
topic
sys_audit_delete (if provided access)
incident (if enabled)
cmdb_ci_business_app (if enabled)
dmn_demand (if enabled)
pm_project (if enabled)
rm_epic (if enabled)
Add the itil (Information Technology Infrastructure Library) role to the user gleansearch. This enables the user to read tables interaction (Interactions) and sc_request (Requests)
Follow the subsequent steps as described in the instructions.
Example of the ACLs:
ACL to read the table (e.g. sys_user)
ACL to read the properties of the table (e.g. sys_user.*)
Connection Instructions Simple
Required permissions for setup
The user setting up this data source must be a ServiceNow Admin.
Other prerequisites
Note: Advanced setup will be required if Glean to support advanced user criteria or start the crawl in Proof Of Concept (POC) mode, which limits how far back Glean will pull data and documents. POC mode is setup by a Glean representative.
All steps are to be done by a ServiceNow administrator. Note that the described steps are for the Tokyo release. The steps may differ slightly if your instance is on a different ServiceNow release. If you have any questions, please contact Glean support.
Glean supports simple permissioning for ITSM, APM and SPM object types. Users with specific roles are granted access to all the documents. If you require a customized role, please reach out to Glean support.
Setup Input
Enter the following information into the Glean admin console in the corresponding fields:
Name: Name of the connector which will be displayed in the Glean interface
Domain Name: Accepts domain or domain URL. Note the domain URL should not include any http prefixes and should follow the format of <domain>.service-now.com. It is preferred to enter the domain URL
User ID: gleansearch
Password: The password from service account setup
OAuth Client ID: Client ID from the application setup
OAuth Client Secret: Client Secret from the application setup
Check any optional criteria if relevant to your configuration
Click Save
Optional checkboxes:
Apply article read criteria: to mirror the system property glide.knowman.apply_article_read_criteria.
Block access with no user criteria: to mirror the system property glide.knowman.block_access_with_no_user_criteria.
Enable fetching template-based knowledge articles: If Knowledge Article templates are enabled in your instance,
Document types Glean to index
ITSM Incidents
APM Business Applications
SPM Demands, Projects and Epics
Connection Instructions Advanced
Required permissions for setup
The user setting up this data source must be a ServiceNow Admin.
Other prerequisites
This version of setup requires you to set up scripted REST API in ServiceNow
All steps must be completed by a ServiceNow administrator. Note that the steps described are for the Tokyo release. The steps may differ slightly if your instance is on a different ServiceNow release. If you have any questions, please contact Glean support.
Create an ACL to be used for the REST API:
Elevate role to get “security_admin” role (This is found on the "System Administrator" Header Banner). Note that by default this is only set for the user account whose name is “admin”
Navigate to Access Control (ACL), and create a new ACL with the following properties:
Set type=Rest_endpoint
Set protection policy=Read only (if possible)
Set Name=GleanSearch
Set Role=knowledge_admin, catalog_admin, itil (only if you want to index ITSM incidents as well)
Set operation=execute
Configure the body of the REST API that provides the User Criteria information for a given user
Navigate to Scripted REST APIs
Create a new API called GleanSearch and API ID gleansearch
Set Protection=”Read only”
Remove existing default acl and add GleanSearch acl as default acl
Create a new REST endpoint
Name=GetUserCriteria
HTTP method=GET
Relative path = /user_criteria
Protection policy=Read only
Ensure Requires Authentication and Requires Authorization are checked
Remove the default Scripted REST external default and set GleanSearch
Verify that the resource path is /api/<API_NAMESPACE>/gleansearch/user_criteria (API namespace value needs to be entered in the corresponding box )
Add the following as the script (function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) { var queryParams = request.queryParams; var userID = new String(queryParams.user); return new sn_uc.UserCriteriaLoader.getAllUserCriteria(userID); })(request, response);
Next create the Service Account if not already done and continue with Connection Instructions Simple
API Endpoints
Glean uses the Table API to crawl relevant tables for ServiceNow content and permissions. For this, we have you create a dedicated ServiceNow user with access to the required tables through the Table API. We also use a Scripted Rest API that is configured as part of the setup to crawl advanced user criteria.
Format of the Table API calls are displayed below
https://<servicenowDomain>/api/now/<tableName>
Additionally, in the case of advanced user criteria, we have you create a scripted REST API endpoint to return the user criteria for a given user. The endpoint looks like:
https://<servicenowDomain>/api/now/<app_scope>/gleansearch/user_criteria
Tables Name | Use case |
sys_user | Users |
sys_user_has_role | User - Role pairs |
sys_user_grmember | User - Group pairs |
user_criteria | User criteria |
kb_knowledge | Knowledge articles |
kb_knowledge_base | Knowledge bases |
kb_uc_can_read_mtom | Knowledge base can read criteria |
kb_uc_cannot_read_mtom | Knowledge base cannot read criteria |
kb_uc_can_contribute_mtom | Knowledge base can contribute criteria |
kb_uc_cannot_contribute_mtom | Knowledge base cannot contribute criteria |
kb_category | Knowledge category |
kb_use | View events for knowledge articles |
sc_cat_item | Catalog items |
sc_cat_item_user_criteria_mtom | Catalog items available for user criteria |
sc_cat_item_user_criteria_no_mtom | Catalog items unavailable for user criteria |
sc_category | Catalog category |
sc_catalog | Catalog |
sys_audit_delete* | Deletions to any of the above tables |
incident* | Incidents |
cmdb_ci_business_app* | Business applications (APM) |
dmn_demand* | Demands (SPM) |
pm_project* | Projects (SPM) |
rm_epic* | Epics (SPM) |
* - only if the corresponding feature is enabled
Content
Doc type | Associate table | Enabled by default | Additional Roles Required |
Knowledge articles | knowledge | yes |
|
Catalog items | sc_cat_item | yes |
|
ITSM incidents | incident | no | itil or sn_incident_read |
ITSM requests aka Request items or RITM | sc_request | no | itil or sn_request_read |
Interactions | interaction | no |
|
APM Business applications | cmdb_ci_business_app | no | sn_apm.apm_user |
SPM Demands | dmn_demand | no | it_demand_user |
SPM Epics | rm_epic | no | scrum_user and safe_scrum_user |
SPM Projects | pm_project | no | it_project_user |
Identity
Users: Information about users within the ServiceNow
Groups: Details about groups within ServiceNow
The identity crawl operates with the following configurations:
Incremental Identity Crawls: These are performed to capture changes since the last crawl.
Full Identity Crawls: These are conducted periodically to ensure all identity data is up-to-date.
Activity
Adds: New Knowledge Articles, CMDB objects, etc. added
Updates: Modifications made to existing Knowledge Articles, CMDB objects, etc..
Permissions Changes: Changes in Knowledge Articles and CMDB objects sharing permissions.
Deletions: Knowledge Articles and CMDB objects that have been deleted.
View Activity: Knowledge Articles and CMDB objects have been viewed.
Rate Limits
None
Update frequency
Content updates for the ServiceNow connector in Glean can happen quite rapidly, depending on the type of update and the configuration settings. Here are the key areas:
Activity Reports: Adds, updates, and permissions changes are crawled every 30 minutes. This means that any new objects, modifications to existing objects, or changes in sharing permissions are detected and processed quickly.
People / Identity Crawls: Changes to group memberships are picked up by the identity crawl, which runs every hour. This ensures that any updates to user groups and their permissions are reflected promptly.
Incremental Crawls: These occur every 1 hours to provide additional reliability beyond the minute-by-minute activity reports.
Full Crawls: The frequency of full crawls can be configured, but they are generally less frequent than incremental crawls at 3 days for Knowledge Articles and 30 minutes for Catalog Items
For the most up-to-date crawler refresh information, please refer to [External] Glean crawling strategy
How the Crawl Works
The ServiceNow crawler follows the traditional crawler strategy, including utilizing the ServiceNow API and the following ways to get and update data:
Identity Crawl: updating and adding People data, including users, groups, and other information
Activity Crawl: Adds, updates, and permissions changes to content
Webhooks: are messages sent by the application to notify Glean of changes in real-time, and then Glean either initiates crawl or picks up the change on the next crawl
Content Crawls: Full crawls the entire defined scope of the application, whereas incremental crawls only capture the changes from the previous full or incremental crawl
Known Limitations in Crawl
Glean does not index Drafts of ServiceNow articles
Unsupported Features
Within the scope of the current content supported, there are no known limitations
Content Configuration
Note: If Inclusion (Green-Listing) options are enabled, only content from the Inclusion content will be indexed. If Exclusion (Red-Listing) options are enabled all content in the exclusions will be removed. If both rules are applied to the same piece of content, then the content will NOT be indexed as the Red-listing rule takes priority.
The rules below should be used MINIMALLY to preserve the enterprise search experience, as most end-users expect to find all content. Most customers do not apply any rules, or apply red-listing rules sparingly for sensitive folders or objects.
Exclusion (Red-Listing) Options
Selected Knowledge Bases can be excluded from the crawl. Please contact your Glean representative to configure this feature.
Inclusion (Green-Listing) Options
Selected Knowledge Bases can be included in the crawl only. Please contact your Glean representative to configure this feature.
Troubleshooting/FAQ
Why do you need access to the sys_audit_delete table?
It’s required for faster updates to permission deletions. This allows us to propagate permission deletion updates significantly faster in large corpuses because we can incrementally crawl changes, rather than rely only on full crawls.
What other API Authentication options are available for ServiceNow? Does Glean support any others besides basic auth?
Glean only supports basic authentication (via service account credentials) right now. Other options that ServiceNow’s APIs support are: OAuth, certificate-based auth, and API tokens. These all still require being mapped to or owned by a user/service account with the appropriate roles.
Do we support any other method to retrieve all the (advanced) user criteria for a given user besides the undocumented UserCriteriaLoader?
Glean does not currently support this method. Please contact your Glean representative for the latest information.
Why do we need the username and password when we use the client id and secret?
Glean needs the credential pair for fetching a refresh token which later gets used to fetch an access token.