Prepare ServiceNow for Alert Escalation

Before you connect Ataccama ONE to ServiceNow, a ServiceNow administrator needs to prepare the ServiceNow instance. ONE connects as a dedicated integration user, so that user needs access to every ServiceNow table ONE reads from or writes to.

You also register an OAuth client that ONE uses to authenticate. OAuth 2.0 is the recommended authentication type. If you use Basic or API Key authentication, set up the integration user, roles, and ACLs in the same way and skip Register an OAuth client for ONE.

When you’re done, connect ONE to ServiceNow with the OAuth client ID and secret, or with the integration user’s credentials or API key.

Before you begin

Your ServiceNow instance must run the Washington DC release or later.
You need the admin role in ServiceNow, and you must be able to elevate to the security_admin role to create access control lists (ACLs).
Decide whether to give the integration user the itil role or custom ACLs for the ticket tables. Users with the itil role typically count toward your ServiceNow fulfiller licenses. See Grant access to the ticket tables.

ServiceNow tables that ONE uses

ONE uses the ServiceNow Table API for every data request. The integration user needs access to the following tables:

Table Access Why ONE needs it

Table	Access	Why ONE needs it
The ticket table, for example `incident`	Read, create, and write	To create tickets, and to check whether a ticket already exists for the alert before creating one.
`sys_db_object`	Read	To list the tables you can create tickets in.
`sys_dictionary`	Read	To show the fields of the selected table, with their data types, in the field mappings.
`sys_glide_object`	Read	To read the data type of each field.
`sys_choice`	Read	To list the available values for fields that have predefined options.
`sys_user`, `sys_user_group`, and any other table that a reference field points to	Read	To list the values you can select for reference fields, such as the assignee or assignment group.

The ticket table, for example incident

Read, create, and write

To create tickets, and to check whether a ticket already exists for the alert before creating one.

sys_db_object

Read

To list the tables you can create tickets in.

sys_dictionary

Read

To show the fields of the selected table, with their data types, in the field mappings.

sys_glide_object

Read

To read the data type of each field.

sys_choice

Read

To list the available values for fields that have predefined options.

sys_user, sys_user_group, and any other table that a reference field points to

Read

To list the values you can select for reference fields, such as the assignee or assignment group.

ONE also reads sys_user when you test the connection.

Create the integration user

In ServiceNow, go to User Administration > Users.
Create a user for ONE, for example ataccama.one.integration.
Select Active and Web service access only.

Web service access only prevents the user from signing in to the ServiceNow UI but still allows API requests.
Save the user.

Create a role for the integration user

Go to User Administration > Roles.
Create a role, for example u_ataccama_one_integration.
Open the integration user and assign the following roles:
- The role you created
- snc_platform_rest_api_access
  
  Without snc_platform_rest_api_access, ServiceNow rejects every API request with 403 User Not Authorized, regardless of the user’s ACLs.

You use the role you created in the ACLs in the following sections.

Grant read access to table and field definitions

To show your ticket tables, their fields, and the values available for each field, ONE reads them from ServiceNow. ServiceNow stores this information in four system tables: sys_db_object, sys_dictionary, sys_choice, and sys_glide_object.

Elevate to the security_admin role.
Go to System Security > Access Control (ACL).
For each of the four tables, create two ACLs in the Global scope, with Type set to record, Operation set to read, and Requires role set to the role you created:
- One with the field set to --None--
- One with the field set to *

Don’t skip sys_glide_object. Field data types in sys_dictionary are references to sys_glide_object, and ServiceNow blanks a reference value if the user can’t read the referenced record. Without read access to sys_glide_object, field mappings in ONE fail with an Insufficient rights to query records error, even though the sys_dictionary ACLs pass.

The new ACLs apply alongside the out-of-the-box ACLs and don’t change access for other users. Don’t edit the out-of-the-box ACLs. Create these ACLs rather than assigning the personalize_dictionary role, which also allows changing table definitions.

Grant access to the ticket tables

Give the integration user access to each table where ONE creates tickets. You can either assign the itil role or create ACLs for each table.

Grant ticket table access with the itil role

Assign the itil role to the integration user. The role covers reading, creating, and updating records in tables based on task, such as incident, and reading the most common reference tables.

Users with the itil role typically count as fulfiller users in ServiceNow Subscription Management. Check with your ServiceNow license owner before you assign the role.

Grant ticket table access with ACLs

For each ticket table, for example incident, create the following ACLs with Type set to record and Requires role set to the role you created:

read on the record, with the field set to --None--.
read on all fields, with the field set to *.
create on the record.
write on the record.
write on all fields, with the field set to *.
write on the correlation_id field. Because correlation_id is inherited from the task table, create this ACL on task.correlation_id.

ONE stores a unique escalation identifier in correlation_id to recognize tickets it has already created. If the integration user can’t write to correlation_id, ServiceNow drops the value without an error, and ONE creates a duplicate ticket each time it retries an escalation.

Grant read access to reference tables

The integration user needs read access to sys_user and sys_user_group. If your field mappings include other reference fields, the integration user also needs read access to the tables those fields point to.

For each of these tables, create a read ACL with the field set to --None-- and a read ACL with the field set to , both with *Type set to record and Requires role set to the role you created.

If you assigned the itil role, the most common reference tables are already covered.

Register an OAuth client for ONE

ONE authenticates with the OAuth 2.0 client credentials grant.

Set the glide.oauth.inbound.client.credential.grant_type.enabled system property to true.

To open the system properties, enter sys_properties.list in the filter navigator. If the property doesn’t exist, create it with Type set to true | false and the value true. Without this property, ServiceNow rejects every token request.
Go to System OAuth > Application Registry.
Create an OAuth API endpoint for external clients.
Set Default Grant Type to Client Credentials.

This field is hidden on the form by default. If you don’t see it, add it to the form with Configure > Form Builder or Configure > Form Layout, depending on your ServiceNow UI. If you have a Now Support account, ServiceNow’s KB1645212 article has the full instructions.
Set the Default user to the integration user.

In the newer Inbound Integration Experience, this field is called OAuth Application User. If the classic Application Registry form doesn’t show the field, configure the client from the Inbound integrations view instead.
Set the default auth scope of the OAuth client.

ONE doesn’t request a scope, so every token gets the client’s default scope. You can use the useraccount scope. To limit the client to the Table API instead, create an auth scope in System OAuth > Auth Scopes, map the Table API to it with a REST API auth scope, and set it as the client’s default.
Copy the Client ID and Client Secret.

ONE uses the integration user’s roles and ACLs for every request. Role changes take effect on the next request, so you don’t need to generate new credentials after you change the user’s access.

Verify the ServiceNow setup

After you connect ONE to ServiceNow, confirm that the integration user has the access it needs:

When you add the connection in ONE, check that Test connection succeeds.

Test connection confirms that ONE can authenticate and make API requests. It doesn’t check access to the ticket tables or to the table and field definitions.
When you add an entry point, check that the ServiceNow table list shows your ticket tables, and that the field mappings show each field with its data type.
In the Ataccama column, select Fixed value for a field with predefined options, such as Incident state, and check that its values are listed.
Select Fixed value for a reference field, such as Assignment group, and check that its values are listed.
Before you use the integration in production, escalate a test alert.
Open the ticket in ServiceNow and check that correlation_id and each mapped field are filled in.
Delete the test ticket.

If any of these checks fails, see Troubleshoot ServiceNow access.

Troubleshoot ServiceNow access

Test connection fails with an OAuth 2.0 token error

If Test connection fails with an error that starts with OAuth2 token request failed (HTTP 401) and includes access_denied, ServiceNow refused to issue a token. ServiceNow returns the same error for every cause, so check all of the following:

The glide.oauth.inbound.client.credential.grant_type.enabled system property exists and is set to true.
Default Grant Type on the OAuth client is set to Client Credentials, and the client is active.
The client ID and client secret match the values in System OAuth > Application Registry. If the secret you entered contains % followed by two characters, such as %2B, it was probably copied in URL-encoded form. Copy the secret from the registry again rather than from an email, a URL, or an API tool export.
The instance URL is correct.

If the error is OAuth2 token endpoint returned non-JSON response, see Requests fail with an unexpected response content type error.

Every request fails with a User Not Authorized error

If requests fail with Access forbidden (HTTP 403): User Not Authorized, check the following:

The integration user has the snc_platform_rest_api_access role.
The Default user on the OAuth client is set to the integration user.
The integration user is active.

Requests fail with an unexpected response content type error

If ONE reports an Unexpected response content type error that mentions text/html, ServiceNow returned an HTML page instead of data. With OAuth 2.0, the same problem can appear as an authentication error, OAuth2 token endpoint returned non-JSON response.

This isn’t an access problem. Check the following:

The instance URL is correct.
The instance is awake. Developer instances hibernate when they’re not in use.
Single sign-on (SSO) isn’t intercepting API requests.

ONE can’t list ServiceNow tables or load field mappings

If the request fails with an Access forbidden (HTTP 403) error, check the ACLs on sys_db_object, sys_dictionary, sys_choice, and sys_glide_object:

Each table has a read ACL with the field set to --None--.
The ACLs were saved in the Global scope.
The role you created is listed in Requires role. To add a row to the Requires role list, double-click the list, then select Update to save the ACL.
The integration user has the role.

Field mappings fail with an insufficient rights error

If loading field mappings fails with Insufficient rights to query records, the integration user can’t read one of the fields ONE filters on, so ServiceNow rejects the whole request.

The most common cause is missing read access to sys_glide_object. Check that you created the ACLs described in Grant read access to table and field definitions.

If the error persists, a field-specific ACL on your instance might override the ACL. Field-specific ACLs can include the query_range operation, which controls whether a field can be used in a query, separately from reading it. In *System Security > Access Control (ACL), filter by names that start with the table name, for example sys_dictionary.. For each field-specific ACL you find, create a matching ACL with Requires role set to the role you created.

Field mappings show no fields or fields with missing values

If the field mappings are empty, or fields are missing their data type or options, the integration user can read the records but not their field values. Check that each of the four tables in Grant read access to table and field definitions has a read ACL with the field set to *.

If a value is still blank, the field might be a reference to a table the integration user can’t read. Grant read access to that table.

Reference field values are empty in the field mappings

If the list of values for a reference field is empty or shows an error, the integration user can’t read the table that the field points to. See Grant read access to reference tables.

Tickets are created without a correlation ID

The integration user can’t write to correlation_id. Create a write ACL on task.correlation_id, as described in Grant ticket table access with ACLs.

Fix this before you use the integration in production, so that retried escalations don’t create duplicate tickets.

ONE doesn’t show changes made in ServiceNow

ONE refreshes ServiceNow table and field information every few minutes. Names of reference values already selected in a field mapping can take up to 10 minutes to update. After a change in ServiceNow, wait a few minutes and open the entry point again. If it still shows the old information, close it and open it once more.

Access still fails after you check the ACLs

If none of the previous solutions apply, use ServiceNow’s security debugging to find the ACL that denies access:

Elevate to the security_admin role.
Turn on Debug Security Rules.
Repeat the action that fails in ONE.

The debug output names the ACL that denies access.
Turn off Debug Security Rules.

Next steps

Connect to ServiceNow: Connect ONE to ServiceNow and add entry points.

Was this page useful?