Generate ServiceNow OAuth Tokens

To connect ServiceNow to a knowledge base, you must either provide your ServiceNow credentials to NiCE Professional Services or enter them in Knowledge Hub yourself. This page describes how to configure the ServiceNow integration with Knowledge Hub. Setting up ServiceNow takes two steps:

Three tasks are the same either way: opening the Application Registry, setting the token lifetimes, and giving the integration user the right permissions.

Complete each of these tasks in the order given.

Before You Begin

Make sure you have the following:

  • Admin access to the ServiceNow instance you want to connect.
  • Access to the Knowledge Hub application in NiCE CXone.
  • A basic understanding of how OAuth works in ServiceNow.

Configure OAuth in ServiceNow

Everything on the ServiceNow side starts here. This is the same whichever setup method you use.

  1. Open your ServiceNow account in web browser and Sign in.

  2. In the top navigation bar, click All.

  3. Navigate to, System OAuth > Application Registry.

    Alternatively, search for System OAuth.

  4. On the Application Registries page, click New at the top right.

  5. Click New Inbound Integration Experience.

  6. Click New integration at the top right of the page.

  7. Click OAuth - Authorization code grant.

  8. Fill in the fields on the New record page.

    Field

    		What to enter
    NameA name for the OAuth entity. For example, Knowledge.
    Provider nameThe name of the service you are connecting to. For example, NiCE Knowledge.
    Redirect URLsThe redirect URL for your region. Find yours in Redirect URLs by Region.
    Client IDServiceNow fills this in for you. Copy it and keep it handy. You need it in Knowledge Hub.
    Client secretServiceNow fills this in for you. Copy it and keep it handy. You need it in Knowledge Hub.

    ServiceNow shows the client secret only once. If you lose it, you have to reset it and set up the connector again.

    This is a public clientLeave this box clear.
    ActiveLeave this box selected. The connection does not work if you clear it.
    CommentsNotes about this configuration. This field is optional.
    NameA name for the OAuth entity. For example, Knowledge.
    Provider nameThe name of the service you are connecting to. For example, NiCE Knowledge.

  9. Under Auth scope, add useraccount. This is the only scope this method needs.

Leave this page open. You set the token lifetimes on it next.

Redirect URLs by Region

The redirect URL is where ServiceNow sends the tokens after it approves Knowledge Hub. It must match the region your NiCE CXone system runs in. Find your region in the table and enter that URL exactly.

Copy the URL character for character. An extra space, a missing slash, or a URL from the wrong region all cause a redirect URI mismatch error when you authenticate later.

Region

 Redirect URI
NA1 https://api-na1.niceincontact.com/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
NA2 https://api-na2.niceincontact.com/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
CA1 https://api-ca1.niceincontact.com/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
AU1 https://api-au1.niceincontact.com/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
AU2 https://api-au2.nicecxone-sov1.au/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
DE and EU1 https://api-eu1.niceincontact.com/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
UK1 https://api-uk1.niceincontact.com/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
UK2 hhttps://api-uk2.nicecxone-sov1.uk/eai-kh-public-services/config/v1/knowledgehub/oauth/callback
JP1 https://api-jp1.niceincontact.com/eai-kh-public-services/config/v1/knowledgehub/oauth/callback

Configure the OAuth Token Settings

Tokens are what let Knowledge Hub keep reading your articles after you sign in. Each one has a lifespan, and when it runs out the connection stops working. These values are the same whichever setup method you use.

ServiceNow does not renew or replace refresh tokens. Whatever lifespan you set here is a hard deadline. When it passes, syncing stops and someone has to authenticate again. Do not leave the refresh token at the 100-day default on a production instance.

  1. Open the OAuth application record that you created.

    If it is not already open, navigate to, System OAuth > Application Registry, and then select your application.

  2. On the same page, expand Advanced options.

  3. In Refresh Token Lifespan, enter the number of seconds before the refresh token expires.

    1. Recommended value:31,536,000(1 year)

    2. Default value:8,640,000(100 days)

  4. In Access Token Lifespan, enter the number of seconds before the access token expires.

    1. Example value:7,200 (2 hours)

    2. Default value:1,800 (30 minutes)

  5. Click Save at the top right of the page.

Make a note of the date your refresh token expires. Authenticate again in Knowledge Hub before that date to avoid a gap in syncing.

Least-Privilege Access (Optional)

This section is only needed if you want to authenticate using a dedicated, restricted integration user instead of an administrator account.

If you are authenticating with an administrator account, you can skip this section and proceed directly Connect ServiceNow to Knowledge Hub.

The account you authenticate with needs permission to read your knowledge articles and the tables that describe them. Roles on their own are not enough, so you also create access control rules. These requirements are the same whichever setup method you use.

Start by giving the integration user these two roles:

  • snc_platform_rest_api_access: Lets the account use the REST Table API.
  • OAuth_user: Lets the account authenticate with OAuth.

These two roles on their own are not enough. ServiceNow still blocks access to the system tables until you create the access control rules described below. Skipping this task is the most common reason a connector authenticates successfully but finds no articles.

Check That the Table API Rule Is Active

If this rule is turned off, the connection fails with a 403 error.

  1. Go to System Security > Access Controls (ACL).
  2. In the filter, enter Name contains Table API.
  3. Open the record and check that Active is set to true.

Create Read Rules for the System Tables

Knowledge Hub reads three system tables to work out which of your tables hold knowledge articles. Create a read rule for each one.

  1. Go to System Security > Access Controls (ACL).
  2. Click New.
  3. Set Type to record and Operation to read.
  4. In the first Name drop-down, select Table [sys_db_object]. Leave the second drop-down set to --None--.
  5. Under Requires role, double-click Insert a new row and select your integration role. For example, x_kh_integration.
  6. Click Submit.
  7. Repeat these steps for Table [sys_dictionary] and Table [sys_glide_object].

Add the Role to the Integration User

Creating the rules is only half the job. The user needs the role as well.

  1. Go to User Administration > Users.
  2. Open the integration user.
  3. Under Roles, click Edit and add your integration role.
  4. Add the personalize_dictionary role as well. ServiceNow can still block access to the dictionary tables without it, and this fixes most permission problems.
  5. Click Save.

The following table summarizes the minimum the integration user needs.

What the account needs to do

 Role or access control rule
Read sys_db_object A custom rule and role, or personalize_dictionary
Read sys_dictionary A custom rule and role, or personalize_dictionary
Read sys_glide_object A custom rule and role
Use the REST Table API snc_platform_rest_api_access
Authenticate with OAuth oauth_user

Your ServiceNow setup is now complete. The rest of the work happens in Knowledge Hub.

Connect ServiceNow to Knowledge Hub

You cannot change the configurations after authentication completes. You can edit them only if source creation or the sync has failed.

  1. In NiCE CXone, click the app selector and select General > AI Studio > Knowledge Hub.

  2. Select ServiceNow from the Knowledge Source drop-down.
  3. Enter your ServiceNow parameters in the corresponding fields.
  4. Click Authenticate at the bottom right of the page.
  5. Log in to ServiceNow in the window that opens.

  6. Click Allow to give Knowledge Hub access to your ServiceNow account.

  7. Wait for the ServiceNow window to close and the Authentication Completed message to appear.
  8. Click Next.
  9. Review the summary, then click Create and Ingest.
  10. The connector status changes to Pending. After five to seven minutes, refresh the page. Manual Sync becomes available.
    • Click Manual SyncTwo arrows forming a circle..
    • Wait for the sync to finish.

      • A large knowledge base can take several hours to sync. You do not need to stay on the page while it runs. Come back later and refresh to check the status.

  11. When the sync finishes, the status changes to Active. Your ServiceNow articles are now available in Knowledge Hub.


Troubleshooting

Use the following table to resolve common ServiceNow connector problems.

Problem

 Possible cause Solution
Invalid client The client ID or client secret is wrong, or the app is not active in ServiceNow. Check both values against the ServiceNow app, and make sure the Active box is selected there.
Invalid scope The useraccount scope is missing or misspelled. Open the ServiceNow app and check the Auth scope section.
Invalid grant The refresh token expired. Authenticate again in Knowledge Hub.
Redirect URI mismatch The redirect URL in ServiceNow does not match your region. Compare the URL in ServiceNow against Redirect URLs by Region. It must match character for character.
Syncing stops after months of working The refresh token reached the end of its lifespan. Authenticate again in Knowledge Hub. To stop this happening again, raise the refresh token lifespan in ServiceNow.