Agent ServiceNow Schema Access using OAuth

The DataSync Agent requires making API calls to your ServiceNow instance in order to obtain the schemas of tables you are sharing. This way the Agent will know the table's structure to create the table properly in the target database.

By default, the DataSync Agent uses Basic Authentication to make API calls to your instance. However, you can also have the Agent use ServiceNow's OAuth 2.0 implementation to make the API calls.

With the OAuth 2.0 implementation, the Agent will initially use your credentials configured in the Agent's configuration file (agent.xml) to request an access token from your ServiceNow instance it will then use for accessing the table schema API. If the access token expires, it will use the refresh token to request a new access token. If the refresh token is expired, it will start the process all over again, using your credentials configured to request a new access token.

 NOTE: The Agent will call to ServiceNow to get the schema for a ServiceNow table the first time it receives a record to insert into the database for that particular table. The Agent won't get the schema again for the table until there's a column change that requires it to get the schema from ServiceNow to understand what the column change should be.

Furthermore, if the Agent is restarted and has the <use_cache/> configuration directive and already has the schema for a table (schemas are stored locally in the Agent's bin/<instance>.service-now.com.schemas_directory folder), it won't get the schema until a column change.

Prerequisites

• Configure your ServiceNow instance as an OAuth API endpoint for external clients. You can also see here and here for additional details on setting this up in your ServiceNow instance.
• Create a ServiceNow user. This user must have the perspectium role in order to access the table schemas through the ServiceNow APIs. You can specify the user to have the Web service access only option selected if this user should only be used for the integration and not be able to login to your ServiceNow instance.

To configure the Agent to use ServiceNow's OAuth implementation, add the following attributes to your <instance_connection> configuration directive underneath <task> within your agent.xml file:

<config>
	<agent>
		<subscribe>
			<task> 
				...     
				<instance_connection auth_type="servicenowoauth" client_id="abcabcabcabc" client_secret="def456^)" password="password123" user="user1">https://instance.service-now.com</instance_connection>
     </task>
		</subscribe>
	</agent>
</config>

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<config>
   <agent>
      <subscribe>
         <task instances="1">
            <task_name>mysql_agent_subscribe</task_name>
            <message_connection password="password123" queue="psp.out.replicator.queue_name" user="user1">https://us-east-1-qatemp.perspectium.net</message_connection>             		<instance_connection auth_type="servicenowoauth" client_id="abcabcabcabc" client_secret="def456^)" password="password123" user="user1">https://instance.service-now.com</instance_connection>             
			<handler>com.perspectium.replicator.sql.SQLSubscriber</handler>
            <decryption_key>The encryption key you want to use</decryption_key>
            <database_type>mysql</database_type>
            <database_server>localhost</database_server>
            <database_port>3306</database_port>
            <database_user>user1</database_user>
            <database_password>password123</database_password>
            <database_parms>autoReconnect=true & characterEncoding=UTF-8 & useSSL=false & serverTimezone=UTC</database_parms>
            <database_max_column_size>251</database_max_column_size>
            <database>databasename</database>
         </task>
      </subscribe>
      <max_reads_per_connect>4000</max_reads_per_connect>
      <polling_interval>15</polling_interval>
      <skip_message_set_processing/>
   </agent>
</config>