Skip to content

ServiceNow Query authentication guide

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