How to integrate ServiceNow with Sapho version 3.9 or greater

Important Note

In order to distinguish Sapho activity from an individual user's activity, we recommend connecting to ServiceNow with a dedicated user account (for example, sapho@company.com) that must have a role with full data access privileges, such as Administrator. This will be particularly useful for audit logs.

Enable API access for required tables

Most of the ServiceNow tables are enabled for access via web services by default. To confirm whether a table you want to synchronize with Sapho is accessible via web services:

Step 1: Sign in

Log in to your ServiceNow instance.

Step 2: Check out table accessibility

Navigate to System Definition > Tables and find the appropriate table.

Click on the table name or info icon to get to the table details. Navigate to the Application Access tab and make sure that the “Allow access to this table via web services” option is checked. If the checkbox is unchecked, check it and click the Update button to save your settings.

Privileges requirements

Since ServiceNow is a fully customizable system and each instance might differ, Sapho accesses two system tables to retrieve the ServiceNow data structure. Therefore the dedicated user that is used for Sapho’s connection must have privileges to access the sys_dictionary and sys_db_object tables.

A. Assign role to the dedicated user

By default, "personalize_dictionary" and "admin" are the only two roles that can read the sys_dictionary table. To assign this role to the dedicated user, Navigate to System Security > Users and Groups > Users. Select the dedicated user, navigate to the Role tab, and click Edit.

Search for the "personalize_dictionary" role and select it. Add it to the Roles List on the right by using the right arrow button, and save your settings.

B. Grant access to a dedicated role

As an alternative to assigning existing roles to the dedicated user, you can create a dedicated role and grant read permission rights that will be specific for that role. An instance uses access control list (ACL) rules, also called access control rules, to control what data users can access and how they can access it. For more information, consult the Security chapter in ServiceNow documentation.

Audit Trail

Once you have created a dedicated user in ServiceNow and set up the connector in Sapho using that user’s account, you will be able to ensure transparency in your audit logs.

Any write-backs from Sapho to ServiceNow will be recorded as being performed by this dedicated user. In some cases, the Table API allows Sapho to distinguish a specific Sapho user, as described in the sections below.

Create Task

When creating a new task type record (eg. Incident, Problem or Change Request) from a Micro App, Sapho automatically adds the "opened_by" parameter to the API request based on the currently logged-in user. If you explicitly define the “opened_by” parameter in the service action parameters settings, it replaces the default value automatically added by Sapho.

Set Approval State

When a Sapho user approves requests within a MicroApp, Sapho automatically adds the sentence "Approval state set by Sapho user <user_name>" to the comment field to distinguish which user performed the approval action.

Create Catalog Request

When creating a new Service Catalog Request from a Micro App, Sapho automatically adds the "requested_for" parameter to the API request based on the currently logged-in user.

Filter Queries

Most ServiceNow entities support filtering which is allowed by the sysparm_query URL parameter of the Table API GET method.

You can choose between predefined queries or write your own custom queries. For more information, consult the ServiceNow REST API Reference and Product Documentation.

Examples

// Only Active objects:
active=true
// Updated in the last 2 days: sys_updated_onONLast%20day@javascript:gs.daysAgoStart(1)@javascript:gs.daysAgoEnd(0)
// Updated in the last 3 hours:
sys_updated_onONLast%20hour@javascript:gs.hoursAgoStart(2)@javascript:gs.hoursAgoEnd(0)
// Updated in the last 4 months: sys_updated_onONLast%20month@javascript:gs.monthsAgoStart(3)@javascript:gs.monthsAgoEnd(0)

Note that if the query (or part of it) is invalid, then the invalid part will be ignored (as specified in the ServiceNow documentation).