Troubleshooting the connector¶

Authentication step errors¶

Issues can occur when connecting to ServiceNow in the installation wizard or running manually the SET_CONNECTION_CONFIGURATION procedure. If encountered errors during this step, please make sure that the user used to install the connector has access to the sys_db_object table.

The error status codes that might be related to ACL issues in the returned JSON object from the SET_CONNECTION_CONFIGURATION procedure are as follows:

• REQUEST_FAILED

You can perform below query similar to the connector’s to verify the access. Until the request doesn’t return the expected result, it won’t be possible to install the connector. For example, if you are using curl to send the HTTP request:

# checking access to the sys_db_object table
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_db_object?sysparm_limit=1"

Where:

servicenow_instance

Specifies the name of your ServiceNow® instance.

username and password

Specify the credentials for your ServiceNow® instance.

Example responses:

• At least some of the fields are returned - the user has the necessary permissions to access the table.

• The response is empty - the user has the permission to access the table, but not to the processed record. It might cause issues at a later point.

• The response contains an error - the user does not have the necessary permissions to access the table.

Validate source step errors¶

Issues might occur when validating source in the installation wizard or running manually the FINALIZE_CONNECTOR_CONFIGURATION procedure. If encountered errors during this step, please make sure that the user used to install the connector has the necessary permissions to access the metadata tables.

The error status codes that might be related to ACL issues in the returned JSON object from the FINALIZE_CONNECTOR_CONFIGURATION procedure are as follows:

• METADATA_TABLE_ACCESS_VALIDATION_ERROR

• JOURNAL_TABLE_ACCESS_VALIDATION_ERROR

You can perform below queries similar to the connector’s to verify the access. Until the requests don’t return the expected results, it won’t be possible to install the connector. For example, if you are using curl to send the HTTP request:

# checking access to the sys_db_object table
# expected fields in the result object: sys_id, super_class, name
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_db_object?sysparm_fields=sys_id,super_class,name&sysparm_limit=1&sysparm_query=name=sys_db_object"

# checking access to the sys_dictionary table
# expected fields in the result object: sys_id, name, element, internal_type
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_dictionary?sysparm_fields=sys_id,name,element,internal_type&sysparm_limit=1&sysparm_query=name=sys_dictionary"

# checking access to the sys_glide_object table
# expected fields in the result object: sys_id, name, scalar_type
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_glide_object?sysparm_fields=sys_id,name,scalar_type&sysparm_limit=1&sysparm_query=name=datetime"

# checking access to the sys_table_rotation table
# expected fields in the result object: sys_id, name
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/sys_table_rotation?sysparm_fields=sys_id,name&sysparm_limit=1&sysparm_query=name=syslog"

# (optional) - check only if deletions auditing is going to be used
# checking access to the journal table
# if known, "&sysparm_query=tablename=<table_name>" or "&sysparm_query=documentkey=<sys_id>" can be appended to the request
# expected fields in the result object: sys_id, sys_created_on, documentkey, tablename
curl -u '<username>:<password>' "https://<servicenow_instance>.service-now.com/api/now/table/<journal_table>?sysparm_fields=sys_id,sys_created_on,documentkey,tablename&sysparm_limit=1"

Where:

servicenow_instance

Specifies the name of your ServiceNow® instance.

username and password

Specify the credentials for your ServiceNow® instance.

journal_table

Specifies the name of your ServiceNow® table used for deletions audit. Usually this has value of sys_audit_delete.

Example responses:

• All of the expected fields are present in the response - the user has the necessary permissions.

• Some of the expected fields are missing - the user does not have the necessary permissions to all of the columns.

• The response is empty - the user does not have the necessary permissions to all of the rows.

• The response contains an error - the user does not have the necessary permissions to the table.

Obtaining troubleshooting data¶

To obtain troubleshooting data, call the GET_TROUBLESHOOTING_DATA stored procedure:

CALL GET_TROUBLESHOOTING_DATA(<from_timestamp>, <to_timestamp>);

Where:

from_timestamp

Specifies the start of dates range (in UTC timezone) for which data should be fetched.

to_timestamp

Specifies the end of dates range (in UTC timezone) for which data should be fetched.

This stored procedure returns the following data in tabular format:

• Configuration information

• Errors experienced by connector

• Ingestion history

The following example shows how to call this stored procedure:

CALL GET_TROUBLESHOOTING_DATA('2024-02-05 10:00:00', '2024-02-10 22:30:00');

You can save the returned data in CSV format to send to Snowflake Support.

Restoring the connector warehouse¶

If the connector loses access to its warehouse, configure a new one by calling the UPDATE_WAREHOUSE stored procedure.

Restoring the database and schema for the ServiceNow® data¶

If the database or schema for the ServiceNow® data is dropped, the only way to recover is by running the UNDROP command. If this command is unavailable, you must reinstall the connector and ingest the ServiceNow® data again.

If a view containing the ServiceNow® data is dropped, it should be recreated automatically the next time the background task responsible for creating them runs.

If one of the tables containing the ServiceNow® data (either the event logs or raw data tables) is dropped and you cannot use the UNDROP TABLE command to recover it, do the following to start the ingestion of the ServiceNow® table again:

• Ensure both event logs and raw data tables for this ServiceNow® table are dropped.

• Disable the ServiceNow® table.

• Use the DELETE_TABLE procedure.

• Enable the ServiceNow® table.

Restoring the notification integration for the connector¶

If the connector loses access to the notification integration object, do the procedures for configuring alerts again, recreating the notification integration object if necessary.

If email notifications are configured via Snowsight then you can just disable and re-enable them to restore the necessary external objects.

Checking if column metadata is present in Snowflake¶

To check if column metadata is present in the sys_dictionary table on Snowflake, execute the following query:

SELECT * FROM <dest_db>.<dest_schema>.sys_dictionary__view WHERE name = '<table_name>' AND element = '<column_name>';

If the table you’re investigating has parent tables (inherited from another table in ServiceNow®) and the column you are looking for was added to the parent table, you should use the parent table name instead.

To list all the tables from which the table you’re interested in inherits, please use the following query:

SELECT
    sys_id,
    name,
    PARSE_JSON(super_class):value::string AS super_class_sys_id
FROM <dest_db>.<dest_schema>.sys_db_object__view
START WITH name = '<table_name>'
CONNECT BY sys_id = PRIOR super_class_sys_id;

If rows are returned, metadata for the column was correctly ingested into Snowflake but the view has not yet been refreshed. Check the status and if:

• the view was refreshed recently but the column is still not present, please contact support.

• the view was not refreshed yet, wait for the next ingestion schedule.

If an empty result is returned, it means that the connector didn’t ingest metadata for this column yet. You need to validate on the ServiceNow® side if the record is visible to the connector and has correct timestamp.

View refresh status¶

To validate when the views for a given table were last refreshed and if the operation was successful, execute the following query:

SELECT flattened_views_status, flattened_views_last_updated FROM tables_state WHERE table_name = '<table_name>';

If the last refresh failed, you may want to query event table and look for errors reported by the connector.

View ServiceNow® column metadata availability¶

It’s possible, that the reason for missing columns in the flattened view is that column metadata cannot be ingested by the connector. This may be caused by ACLs preventing the row in the sys_dictionary table from being returned by the Table API. Another possible reason is a past timestamp value in the sys_updated_on column. It can also be the case that the column/table definition was imported from a different ServiceNow® instance. To determine if the connector can access column metadata execute GET request to the following endpoint:

https://<servicenow_instance>.service-now.com/api/now/table/sys_dictionary?sysparm_query=name=<table_name>^element=<column_name>

If an empty result is returned the connector cannot access the column. The column may be protected by an ACL or not present.

If a column definition was returned, examine the value of the sys_updated_on field. Confirm the date matches the expected time when the column was added to the table. If it was imported from another instance it may show the point in time when the column was created. The CDC (incremental updates) mechanism in the connector may not notice that the record dated in the past was added. In this case, trigger a reload of sys_dictionary table.