User Tools

Site Tools


amqp_replicator

AMQP Replicator

Purpose

This document outlines the Perspectium solution for providing bulk and dynamically shared data from a ServiceNow instance to a customer's AMQP environment.

Support Contact

AMQP Handler

Perspectium’s Message bus leverages AMQP technology. Currently, the implementation in use is the Rabbit MQ platform. Data that is shared or published from a ServiceNow instance using either Perspectium’s bulk share or dynamic sharing solutions is staged within the Perspectium Cloud. In cases where a customer want to leverage their own Rabbit MQ platform to house the data replicated from the ServiceNow instance they can use the Perspectium AMQP handler which runs as a task within the Perspectium Replicator Agent will move the replicated data from the Perspectium Cloud Message Bus to the customer’s on premise AMQP environment. The Replicator agent can be run from within the Perspectium Cloud or on the customer’s premise.

Replicated Data

The data that gets published to the customer’s AMQP queue is in XML format. The root or parent node of the XML is the name of the table within the ServiceNow instance that is being replicated.Following the table name is the element psp_table_action. The value of this element represents the action that caused the data to be replicated. The possible values include:

  1. bulk - this is set if data was replicated using Perspectium’s bulk share technology.
  2. insert - this is set if the data was replicated using Perspectium’s bulk share technology with the insert option set or by its dynamic share technology when a new record has been created.
  3. update - this is set when the record has been altered or updated and the table has been configured to be shared using Perspectium’s dynamic share technology.
  4. delete - this is set when a dynamically shared table contains a record that has been deleted.

The remainder of the XML contains an element for each column in the associated table and it’s value. Currently, every column in the table is represented. Each message published to the target AMQP environment represents a row within the table. The XML does not provide the type of the data represented by the column such as whether it’s a number, a string, a date etc., only the name of the column is provided. You can however, use the name of the table which is provided and make a call the the Service-Now SCHEMA processor,providing the name of the table and obtain an XML document which reflects the columns and corresponding data types using a Service-Now internal data type mapping. For example, to obtain the schema of the incident table you would make the following REST based GET:

https://myinstance.service-now.com/incident.do?SCHEMA

The response would look similar to the following excerpt:

<incident><element name="upon_approval" internal_type="string" max_length="40"
choice_list="true"/><element name="location" internal_type="reference" max_length="32"
choice_list="false" display_field="name" reference_table="cmn_location"
reference_field_max_length="100"/><element name="expected_start"
internal_type="glide_date_time" max_length="40" choice_list="false"/><element
name="reopen_count" internal_type="integer" max_length="40" choice_list="false"/><element
name="close_notes" internal_type="string" max_length="4000" choice_list="false"/><element
name="impact" internal_type="integer" max_length="40" choice_list="true"/><element
name="correlation_id" internal_type="string" max_length="100" choice_list="false"/></incident>

See the Service-Now wiki for additional information.

Examples

Below is the simplest example which has been contrived for representation. The ServiceNow user created the table u_my_table and then bulked shared it using Perspectium’s bulk share technology. The table was created with a single column, u_name. The table happens to contain only a single row when it’s bulk shared. The customer’s AMQP platform will receive a single message which is shown below.

  <?xml version="1.0" encoding="ISO-8859-1"?>
  <u_my_table><psp_table_action>bulk</psp_table_action><u_name>Billy Wong</u_name></u_my_table>

As you can see, the table name, u_my_table is represented as the name of the parent node. The action used to replicated the data is ‘bulk and is the value for the psp_table_action element and thecolumn u_name is the name of an element whose value is the value of the actual column within the ServiceNow table, which for our example is Billy Wong.

If the table had contained additional records or rows then they would also be published to the customer’s AMQP environment with the only difference being the value of the u_name column.

In the following example the action is update and the new value is ‘Mr. Billy Wong’. In cases where the publisher of the data is the Perspectium technology running within a Service-Now instance the row will always include the sys_id column, which is a globally unique identifier for the row. This field can therefore be used to perform a lookup in another repository to determine if it already exists and if so a true update would be performed. If the row cannot be located using the sys_id then it could just be added to the repository.

  <u_my_table><psp_table_action>update</psp_table_action><sys_id>278902510f610e0011acc3ace1050e5d</sys_id> <u_name>Mr. Billy Wong</u_name></u_my_table>

The following entry represent a row that has been deleted. Again, the sys_id column can be used as the key for referencing the row within a repository in order to delete it..

  <u_my_table><psp_table_action>delete</psp_table_action><u_name>Mr. Billy Wong</u_name>  <sys_id>278902510f610e0011acc3ace1050e5d</sys_id></u_my_table>

Configuration

The following configuration directives are used to configure the target AMQP environment from within Replicator Agent’s agent.xml file.

Configuration Directive Use
replicate_to_server_uri URI to contact the AMQP server
replicate_to_server_user specifies a user that has access to the server. NOTE: If using a vhost, you would specify it here as VHOST_NAME/USERNAME
replicate_to_server_password specifies the password for the configured user
replicate_to_queue replicate the message to the configured queue
replicate_to_exchange replicate the message to the configured exchange
replicate_to_exchange_routing_key used to set the routing key of the message

Configurations Example

The following is an example of how to configure the AMQP handler to interface with another AMQP platform.

  <task>
  <task_name>replicate_to_amqp_server</task_name>
  <handler>com.perspectium.replicator.file.AMQPHandler</handler>
  <replicate_to_server_uri>amqp://customer.amqpserver..net</replicate_to_server_uri>
  <replicate_to_server_user>amqp_user</replicate_to_server_user>
  <replicate_to_server_password>*****</replicate_to_server_password>
  <replicate_to_exchange>theExchange</replicate_to_exchange>
  <replicate_to_exchange_routing_key>replicated_data</replicate_to_exchange_routing_key>
  </task>
amqp_replicator.txt · Last modified: 2019/04/09 12:43 by paul.jensen