ServiceNow - Serval Documentation

About ServiceNow

ServiceNow is an IT service management (ITSM) platform that manages tickets, incidents, change requests, and IT assets.

What the ServiceNow integration enables

Capability	Description
Ticket Sync	Native bidirectional sync between Serval tickets and ServiceNow incidents
Knowledge Base	Sync knowledge articles from ServiceNow directly into Serval for AI-powered assistance
Workflow Automation	Build Serval workflows using the ServiceNow Table API, Catalog API, and Change Management API

ServiceNow Configuration

This integration requires a dedicated service account with specific, limited permissions. Do not use a personal account or admin account. Following the principle of least privilege ensures security and auditability.

Prerequisites

Before configuring the ServiceNow integration in Serval, ensure you have:

Access to your ServiceNow instance as an administrator
Permissions to create users, roles, and ACLs
Knowledge of your ServiceNow instance name

Step 1: Create a Dedicated Integration User

Navigate to User Administration

Log in to your ServiceNow instance as an administrator
In the application navigator search bar, type “Users” and select User Administration → Users
Click New to create a new user

Configure User Details

Fill in the required user information:

Field	Value
User ID	`serval.integration`
First name	`Serval`
Last name	`Integration`
Active	✅ Checked
Web service access only	✅ Checked (recommended for API-only accounts)
Internal Integration User	✅ Checked (if available in your ServiceNow version)
Photo (Optional)	Download the Serval logo then select it from your downloads

Setting “Web service access only” ensures this account cannot be used for interactive login, improving security.

Click Submit to create the user.

Set the User Password

On the Users page, search for the user you just created and click on it
Click Set Password
Click Generate Password
Important: Click the Copy button to copy the password and save it securely

Save this password immediately — you will not be able to view it again. You’ll need it when configuring Serval.

Click Submit

Step 2: Create a Custom Role for Serval

Creating a custom role with granular permissions is the recommended approach for production environments. This follows the principle of least privilege and provides better security than using out-of-the-box roles like itil or admin.

Create the Custom Role

In the navigator, search for “Roles” and select User Administration → Roles
Click New
Fill in the role details:

Field	Value
Name	`x_serval_integration`
Description	`Custom role for Serval integration with least-privilege API access`

Click Submit

Add Base Roles

Open the role you just created and scroll down to the Contains Roles related list. Add the following base roles:

Role	Purpose
`rest_api_explorer`	Enables REST API access
`personalize_choices`	Allows reading sys_choice values
`personalize_dictionary`	Allows reading sys_dictionary for field definitions

These base roles provide the foundational REST API capabilities. We will add granular table access via ACLs in the next step.

Step 3: Configure Table Access via ACLs

Serval requires specific read/write access to various ServiceNow tables. You’ll create Access Control List (ACL) rules to grant only the necessary permissions.

Required Table Access
Create ACLs
Alternative: Use OOB Roles

The following tables require access:

Incident Management Tables

Table	Read	Create	Write	Fields
`incident`	✅	✅	✅	All standard incident fields
`sys_journal_field`	✅	❌	❌	Comments and work notes

Service Catalog Tables

Table	Read	Create	Write	Fields
`sc_cat_item`	✅	❌	❌	Catalog item details
`sc_request`	✅	✅	❌	Service requests
`sc_req_item`	✅	✅	✅	Requested items

Configuration Tables (Read-Only)

Table	Read	Create	Write	Purpose
`sys_user`	✅	❌	❌	User lookup for assignment
`sys_user_group`	✅	❌	❌	Assignment group lookup
`sys_choice`	✅	❌	❌	Field dropdown values
`sys_dictionary`	✅	❌	❌	Field definitions
`cmdb_ci_service`	✅	❌	❌	Business services

Knowledge Base Tables (Read-Only)

Table	Read	Create	Write	Purpose
`kb_knowledge_base`	✅	❌	❌	Knowledge base metadata
`kb_category`	✅	❌	❌	Knowledge categories
`kb_knowledge`	✅	❌	❌	Knowledge articles

For each table that requires access, create appropriate ACLs:

Navigate to ACLs

In the navigator, search for “Access Control (ACL)”
Select System Security → Access Control (ACL)

Create Read ACLs

For each table that requires read access, create a new ACL:

Click New
Set Type to record
Set Operation to read
Set Name to the table name (e.g., incident)
In the Requires role related list, add your custom role x_serval_integration
Click Submit

Repeat for all tables listed in the Required Table Access tab.

Create Write ACLs

For tables that require create or write access:

Click New
Set Type to record
Set Operation to create or write as needed
Set Name to the table name
In the Requires role related list, add your custom role x_serval_integration
Click Submit

Create write ACLs for:

incident (create, write)
sc_request (create)
sc_req_item (create, write)

Using out-of-the-box roles is simpler but grants more permissions than necessary. Only use this approach for development/testing or if your organization’s security policy permits.

Instead of creating custom ACLs, you can assign these out-of-the-box roles to the integration user:

Role	Purpose	Notes
`itil`	ITSM functionality (incidents, problems, changes)	Grants broad ITSM access
`catalog`	Service catalog access	For catalog item and request access
`knowledge`	Knowledge base access	For knowledge article sync

To assign roles:

Open the integration user record
Scroll to the Roles related list
Click Edit
Add the roles from the list above
Click Save

Step 4: Assign the Custom Role to the Integration User

Open the User Record

Navigate to User Administration → Users
Find and open the serval.integration user

Add the Custom Role

Scroll down to the Roles related list
Click Edit
Add the x_serval_integration role (or the OOB roles if you chose that approach)
Click Save

Step 5 (Optional): Verify API Access

This step is optional but recommended to verify your configuration before connecting to Serval. If you encounter issues connecting, use these methods to troubleshoot.

Test with REST API Explorer

In the navigator, search for “REST API Explorer”
In the Namespace dropdown, select now
In the API Name dropdown, select Table API
Click Send to test a simple query

If you see a successful response with data, the API access is working correctly.

Test with cURL (Optional)

You can also test from the command line:

curl -X GET \
  'https://YOUR_INSTANCE.service-now.com/api/now/table/incident?sysparm_limit=1' \
  -H 'Accept: application/json' \
  -u 'serval.integration:YOUR_PASSWORD'

Replace YOUR_INSTANCE and YOUR_PASSWORD with your actual values.

Step 6: Identify Your ServiceNow Instance

Your ServiceNow instance name can be found in your ServiceNow URL:

If your ServiceNow URL is https://mycompany.service-now.com, then:
- Instance Name: mycompany

The instance name is the subdomain portion of your ServiceNow URL.

Serval Configuration

Once you have created the integration user with appropriate permissions, follow these steps to configure the integration in Serval:

Navigate to ServiceNow App

In Serval, go to Apps → Available → ServiceNow → Connect
The ServiceNow configuration form will appear

Enter Configuration Details

Fill in the following fields with the information from your ServiceNow setup:

Field	Description	Example
Instance Name	Your ServiceNow instance identifier	`mycompany`
Username	The username of your integration user	`serval.integration`
Password	The password for your integration user	`your_secure_password`

Test the Connection

Navigate to the API Integration tab
Click Run on the healthchecks to verify that Serval can successfully authenticate with your ServiceNow instance

Need additional help with your ServiceNow integration? Contact [email protected] for technical assistance or advanced configuration questions.

Integrations

​About ServiceNow

​What the ServiceNow integration enables

​ServiceNow Configuration

​Prerequisites

​Step 1: Create a Dedicated Integration User

​Step 2: Create a Custom Role for Serval

​Step 3: Configure Table Access via ACLs

​Incident Management Tables

​Service Catalog Tables

​Configuration Tables (Read-Only)

​Knowledge Base Tables (Read-Only)

​Step 4: Assign the Custom Role to the Integration User

​Step 5 (Optional): Verify API Access

​Step 6: Identify Your ServiceNow Instance

​Serval Configuration

About ServiceNow

What the ServiceNow integration enables

ServiceNow Configuration

Prerequisites

Step 1: Create a Dedicated Integration User

Step 2: Create a Custom Role for Serval

Step 3: Configure Table Access via ACLs

Incident Management Tables

Service Catalog Tables

Configuration Tables (Read-Only)

Knowledge Base Tables (Read-Only)

Step 4: Assign the Custom Role to the Integration User

Step 5 (Optional): Verify API Access

Step 6: Identify Your ServiceNow Instance

Serval Configuration