Skip to content
LiitoraLiitoraLiitora

Connect ServiceNow

Who this is for: admins who connect Liitora to ServiceNow, for example to open incidents from alerts, add notes to them, order catalog items or look up users.

Before you start: you need the Manage connections permission in Liitora (Admin and Editor). In ServiceNow you need an admin who can create users (user_admin or admin) and, for OAuth, set up inbound integrations (oauth_admin, mi_admin or admin).

Liitora works in your own ServiceNow instance as a dedicated integration user. Every call runs as that user, so it can do only what its roles allow, and ServiceNow’s access rules apply to it like to any user. You can turn it off at any time in ServiceNow.

The ServiceNow connection template fills in everything that is the same for every company. You enter only your instance address and pick how Liitora signs in:

  • OAuth client credentials (recommended). Your admin creates an OAuth client for Liitora that acts as the integration user. Liitora gets a short-lived token from your instance and never sends a password with the requests.
  • User name and password. Liitora signs in as the integration user with its password on every request. Use it only when your admin can’t set up OAuth.

What the template sets for you

Section titled “What the template sets for you”

These settings come from the template and can’t be changed, so the connection only ever reaches your instance:

Setting Value
Address https://<your instance>.service-now.com
Sign-in OAuth client credentials at https://<your instance>.service-now.com/oauth_token.do, or HTTP basic authentication
Other hosts it may call none

You can enter the full address, like https://acme.service-now.com, or only the instance name, acme. The address must be on service-now.com and start with https://. Anything else is refused, such as another domain, a port, a path or a user name in the address, so a typo can’t send your sign-in anywhere else. Instances on their own domain name aren’t supported yet.

Create the integration user

Section titled “Create the integration user”
  1. In ServiceNow, open User Administration > Users and select New.
  2. Give it a User ID people will recognise, for example liitora.integration, and a name such as Liitora integration.
  3. Select Web service access only. The user can then sign in only through the API, never to the ServiceNow UI, a portal or single sign-on. On newer releases you can set the identity type to Machine, which does the same.
  4. Select Internal Integration User if your instance shows it.
  5. Save the user.

Use this user for Liitora only. ServiceNow counts rate limits per user, so a user of its own also gets a limit of its own.

Give the user only what it needs

Section titled “Give the user only what it needs”

Add only the roles for what your workflows do:

What the workflow does ServiceNow role
Read, create and update incidents, add work notes and comments itil
Create and update incidents only sn_incident_write, plus a role that may read users if a workflow looks up callers
Read and update requests and requested items itil
Order catalog items a role that may order the items, see below
Find users by email a role that may read users (sys_user), such as itil

Leave out admin. The integration user doesn’t need rest_api_explorer either: that role is only for the REST API Explorer in the UI.

Some instances turn on the access rule for the Table API, which ServiceNow ships turned off. If yours has, the user also needs the role that rule asks for. Ask your ServiceNow admin.

To order catalog items for other people, your ServiceNow admin must allow the integration user to order for someone else, with the glide.sc.req_for.roles settings. Without that, Liitora can order only for the integration user itself.

Set up OAuth

Section titled “Set up OAuth”
  1. On the Zurich release and later, open Machine Identity Console > Inbound integrations and select New integration. Pick the OAuth client credential grant.
  2. Give it a name, such as Liitora, and fill in the provider name. Keep Active on.
  3. Link it to the integration user, so the token carries that user’s roles. On some releases the field is called OAuth Application User.
  4. Don’t mark the client as public. The client credentials grant is for confidential clients only.
  5. Copy the Client ID and the Client secret.

On older releases such as Xanadu, an admin first turns the grant on with the system property glide.oauth.inbound.client.credential.grant_type.enabled set to true, and adds the OAuth Application User field to the OAuth form.

If your instance uses REST API access policies, make sure a policy allows OAuth for the Table API and the Service Catalog API. When a policy is linked to an API, only the sign-in methods in it work.

Add the connection in Liitora

Section titled “Add the connection in Liitora”
  1. Open Secrets and add a secret of the kind OAuth client, for example snow_oauth. Put the client ID in Client ID and the client secret in Client secret. See Add a secret.
  2. Open Connections and select Add a connection.
  3. Under Start from, pick ServiceNow.
  4. Type the Name, for example snow. Workflows use this name.
  5. Pick the Environment. Add a Test setup too if you test workflows against a separate ServiceNow instance, such as your sub-production instance.
  6. Leave Sign-in method at OAuth client credentials (recommended).
  7. Type the Instance address.
  8. Under Secrets, type snow_oauth for both Client ID and Client secret, or select Suggest names. If the secret doesn’t exist yet, select Ask for it so someone adds the value.
  9. Select Save, then Test connection.

Test connection signs in and reads the ID of one user, nothing else. If it says the sign-in failed, check the client ID and secret, that the integration is active and linked to the user, and that the user is active. If it says access was refused, the user lacks a role that may read users, or an access policy blocks OAuth.

Your AI assistant can do steps 2 to 8 with the create_connection_from_template tool. It asks you for the instance address. It never sees the client secret.

Use a user name and password instead

Section titled “Use a user name and password instead”

If your admin can’t set up OAuth:

  1. Give the integration user a long, random password.
  2. In Liitora, open Secrets and add a secret of the kind Basic auth, for example snow_user, with the user’s User ID as the user name and its password.
  3. Add the connection as above, but pick User name and password as the Sign-in method.
  4. Under Secrets, type snow_user for both User name and Password.
  5. Select Save, then Test connection.

Use this only with a Web service access only user. Change the password now and then, and update the secret when you do. See Rotate and expire secrets.

When ServiceNow slows you down

Section titled “When ServiceNow slows you down”

ServiceNow’s documentation shows no default rate limit for API calls. Your ServiceNow admin can set one per user in the Rate Limit Rules table, and it is theirs to set. When a workflow goes over it, ServiceNow answers 429 Too Many Requests with a Retry-After time. Liitora waits that long and tries again when the wait is up to a minute. Longer waits end the call, and the step’s own retry: setting decides what happens next.

ServiceNow also stops a Table API call that takes longer than 60 seconds. Ask for small pages and few fields in workflows that read many records.

Before you rely on it

Section titled “Before you rely on it”

We built and tested this connection against a stand-in for ServiceNow made from ServiceNow’s documentation. Some details differ between releases and instances, such as the values of the incident state or the fields needed to resolve an incident. Try your workflows on a test instance first.

Sources

Section titled “Sources”

Written from ServiceNow’s own documentation:

Next steps

Section titled “Next steps”