Before You Connect

Before you connect to ServiceNow, ensure that your ServiceNow environment is properly configured. This enables the driver to retrieve metadata and query data successfully.

For an authenticating user to connect to ServiceNow, they must have at least Read permissions to access listing metadata such as:

• sys_db_object (required for all data)
• sys_dictionary (required to retrieve ServiceNow schema information)
• sys_glide_object (required for certain ServiceNow table metadata)

Accessing listing metadata involves two steps:

1. Create all required Access Control Lists (ACLs) to enable access to each required system table.
2. Assign the appropriate role to the authenticating user.

Prerequisite to Creating ACLs

To create ServiceNow ACLs for the system tables, an admin must temporarily elevate their own session:

1. In the user menu, click Elevate role.
2. Select security_admin and click Update.

Step 1: Enable Access to Each System Table

To enable access to each system table, ensure that both table-level and field-level permissions are granted. To do this, follow ServiceNow's security principle of least privilege by creating a dedicated read-only role (for example, x_connector_metadata_reader). You can then assign this custom role to the ACLs that you create in the following steps.

READ sys_db_object

To enable access to sys_db_object:

1. Navigate to System Security > Access Controls.
2. To create a new ACL object, select New.
   • For Type, select record.
   • For Operation, select read.
   • For Name, select Table [sys_db_object] in the first drop-down and --None-- in the second drop-down. (Table-level read)
   • In the Requires role section, double-click the Insert a new row... text box. Search for and select your custom role (for example, x_connector_metadata_reader).
3. To create the ACL object, click Submit.
4. Now create a second ACL for field-level read on all fields of sys_db_object:
   • For Type, select record.
   • For Operation, select read.
   • For Name, select Table [sys_db_object] in the first drop-down and * in the second drop-down (that is, sys_db_object.*).
   • In the Requires role section, add the same custom role.

READ sys_dictionary

To enable access to sys_dictionary:

1. Navigate to System Security > Access Controls.
2. To create a new ACL object, select New.
   • For Type, select record.
   • For Operation, select read.
   • For Name, select Table [sys_dictionary] in the first drop-down and --None-- in the second drop-down. (Table-level read)
   • In the Requires role section, double-click the Insert a new row... text box. Search for and select your custom role (for example, x_connector_metadata_reader).
3. Click Submit to create the ACL object.
4. Create a second ACL for field-level read on all fields of sys_dictionary:
   • For Type, select record.
   • For Operation, select read.
   • For Name, select Table [sys_dictionary] in the first drop-down and * in the second drop-down (that is, sys_dictionary.*).
   • In the Requires role section, add the same custom role.

READ sys_glide_object

To enable access to sys_glide_object:

1. Navigate to System Security > Access Controls.
2. To create a new ACL object, select New.
   • For Type, select record.
   • For Operation, select read.
   • For Name, select Field class [sys_glide_object] in the first drop-down and --None-- in the second drop-down. (Table-level read)
   • In the Requires role section, double-click the Insert a new row... text box.
   • Search for and select your custom role (for example, x_connector_metadata_reader).
3. To create the ACL object, click Submit.
4. Now create a second ACL for field-level read on all fields of sys_glide_object:
   • For Type, select record.
   • For Operation, select read.
   • For Name, select Field class [sys_glide_object] in the first drop-down and * in the second drop-down (that is, sys_glide_object.*).
   • In the Requires role section, add the same custom role.

Notes:

• If your configuration enables database views (for example, using the IncludeDatabaseViews property), you must create the same pair of read ACLs for sys_db_view, sys_db_view_table, and sys_db_view_table_field.
• If you surface descriptions or display column names (for example, using the ShowDescriptions or UseDisplayColumnNames properties), you must create the same pair of read ACLs for sys_documentation.
• The API and the UI enforce the same security. Users must pass both table-level and field-level ACLs on each target business table to read or write records. If either ACL fails, access is denied.
• Inherited tables: Many application tables extend a parent (for example, incident extends task). Inherited fields are governed by the parent's ACLs. Ensure the user's roles satisfy ACLs on the child and any parents.
• Business tables (for example, incident) require their own roles/ACLs; metadata ACLs alone do not grant business data access.

Step 2: Assign the Role to the Authenticating User

After creating all ACLs above, perform these steps once:

1. Navigate to User Administration > Users > Select authenticating user > Roles > Edit....
2. Add the custom role you required on the ACLs (for example, x_connector_metadata_reader) to the authenticating user.