ServiceNow Query Authentication Guide
    • Dark
      Light

    ServiceNow Query Authentication Guide

    • Dark
      Light

    Article Summary

    Overview

    This is a step-by-step guide to creating an OAuth entry, acquiring credentials, and authorising the ServiceNow Query connector for use in Matillion ETL.

    Important Information

    • The ServiceNow Query component uses an OAuth for third-party authentication.
    • While connector properties may differ between Cloud Data Warehouses, the authentication process remains the same.


    Creating an OAuth Entry in Matillion ETL

    1. In Matillion ETL, on the top left corner of the screen, click Project and then click Manage OAuth.

      Please Note

      If a ServiceNow Query component has already been added to an Orchestration Job, the Manage OAuth window may also be accessed using the following method:

      1. Click the ServiceNow Query component's icon to open the Properties panel at the bottom of the screen.
      2. Click ... next to the Authentication property, and finally click Manage in the pop-up window.
      Project dropdown menu

      Project dropdown menu

    2. Copy the Callback URL in the field at the top of the window as this will be required in Acquiring Third-Party Credentials.

    3. Click + in the bottom left corner of the window to open the Create OAuth Entry window.

      New OAuth entry

      New OAuth Entry

    4. Click on the Service dropdown menu and select ServiceNow. Then, provide a name for the OAuth in the Name field and click OK.

      Create OAuth Entry window

      Create OAuth Entry window

    5. On returning to the Manage OAuth window, check the list of OAuths to ensure the new entry is listed.

      Please Note

      This entry is Not Configured. Configuration of the OAuth entry will be discussed in Authorising for use in Matillion ETL.

      OAuth Entry list

      New Entry listed on Manage OAuth window


    Acquiring Third-Party Credentials

    1. Navigate to the ServiceNow Developers portal. Click Sign In on the right side of the navigation bar. The browser will then redirect to a login screen. Enter valid credentials to continue.

      Log in to ServiceNow Developers portal

      Log in to ServiceNow Developers portal

    2. Next, click the user's initials in the navigation bar—for example in this instance, the initials are AG.

      Manage Instance

      Manage Instance

    3. Now, on the My Instance page, click the instance URL.

      My Instance

      My Instance

      Your instance's URL can be accessed from either clicking the account icon in the top right, or from the Your Instance tab.

      Your Instance Instance

      My Instance: second method

    4. The browser will redirect to a login screen. Enter valid credentials for your instance and click Login.

      Please Note

      Take note of the username and password used to log in to the instance, as well as the instance name (the subdomain of the URL, i.e. subdomain.service-now.com) as they will be required in configuring OAuth in Matillion ETL in Authorising for use in Matillion ETL.

      Log in to My Instance

      Log in to My Instance

    5. Once logged in, scroll down the sidebar menu on the left to System OAuth, then click Application Registry.

    6. In the Application Registry window, click New on the window header.

      Application Registry

      Application Registry

    7. Then, in the OAuth application window, click Create an OAuth API endpoint for external clients.

      Create OAuth API endpoint

      Create OAuth API endpoint

    8. This will open a "New record" in a new dialog. In this dialog, provide details for the following fields:

      • Name: provide a unique name for the app
      • Redirect URL: paste the Callback URL (copied earlier from the Manage OAuth window from the Matillion ETL), then click Submit

      Please Note

      Before entering the Callback URL, Unlock will need to be clicked to reveal the field.

      Provide application details

      Provide application details

    9. The browser will return to the Application Registry window. Click the <Name of the newly created app> in the app list.

      Find newly created app on list

      Find newly created app on list

    10. Now, in the new app window, copy the Client ID and Client Secret as they will be required later during Authorizing for use in Matillion ETL.

      Please Note

      • Before the Client Secret can be copied, click Unlock to make it visible.
      • Additionally, when copying the codes, some browsers may add a space to the end of the string. Watch out for this as it will cause the credentials to fail.
      Copy the Client ID and Client Secret

      Copy the Client ID and Client Secret

    11. Click the user menu (in the example this is System Administrator) and then click Elevate Roles.

      Elevate Roles

      Click the username and then click Elevate Roles

    12. In the Elevate Roles dialog, ensure that the security_admin box is ticked.

      Security Admin

      Tick the security_admin checkbox

    13. In the vertical navigation bar on the left, scroll down to and click System Security and then click Access Control (ACL). Access Control

      System security → Access Control

    14. Click New.

      New ACL

      New ACL object

    15. In the New record dialog, ensure the following:

      1. Set "Type" to "record".
      2. Set "Operation" to "read".
      3. Set "Name" to "Table [sys_db_object]" in the first drop-down menu. Leave the second drop-down menu set to "-- None --"
      4. In the "Requires role" section, double-click the text box that says "Insert a new row..." (see the insertion point) and then search for and select your desired role. Available roles are activated when you start typing. Click the tick button to confirm.
      5. Click Submit.

      Access to the sys_glide_object is required for certain ServiceNow table metadata. You can enable access to this by repeating the above procedure, but instead selecting Field class "[sys_glide_object]" for the ACL's name.

      New ACL

      New Record config

    16. In the vertical navigation bar on the left, scroll down to and click User Administration and then click Users. Then, select the relevant user to edit roles for.

      User Administration

      User Administration → Users

    17. Click Roles and then click Edit.

      Edit roles

      Roles → Edit

    18. Using the → and ← buttons, add the desired roles from the collection. Additionally, access to sys_dictionary is required to retrieve schema information from ServiceNow. You can enable access to this by adding the "personalize_dictionary" role from collection, as in the image below. Click Save to close this window.

      Add desired role

      Add desired roles


    Authorising for Use in Matillion ETL

    1. Return to the Manage OAuth window on Matillion ETL and click next to the previously created OAuth entry. This will open the Configure OAuth window.

      Configure OAuth settings

      Configure OAuth settings

    2. Using the codes copied from the ServiceNow Developers portal earlier, provide details for the following fields:

      Configure OAuth settings

      Configure OAuth settings