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

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

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

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.

   

   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

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

   

   Manage Instance

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

   

   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.

   

   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

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

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

   

   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, will need to be clicked to reveal the field.

   

   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

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 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

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

    

    Click the username and then click Elevate Roles

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

    

    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).

    System security → Access Control

14. Click New.

    

    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 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 → Users

17. Click Roles and then click Edit.

    

    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 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

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

   • Client ID – enter the Client ID
   • Client Secret – enter the Client Secret
   • Instance – enter the ServiceNow instance name
   • Username – enter the ServiceNow instance username (the subdomain of the URL, i.e. subdomain.service-now.com)
   • Password – enter the ServiceNow instance password, then click OK
   

   Configure OAuth settings