User Tools

Site Tools


sql_agent_plugins

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

sql_agent_plugins [2015/07/29 15:52] (current)
mark.english created
Line 1: Line 1:
 +===== The SQL Subscriber Plugin Framework =====
  
 +<WRAP round important>​
 +The Plugin support described here is provided only when using the SQLSubscriber handler. ​
 +</​WRAP>​
 +
 +==== SQL Subscriber Plugin ====
 +
 +This section will be discussing the the plugin capabilities provided by the SQL Subscriber handler which is used when subscribing to SQL table data shared from a ServiceNow instance.
 +
 +The SQL Subscriber handler currently supports plugins created using the Java language.
 +
 +Each class or plugin must implement the ISQLSubscriberPlugin interface which looks like the following:
 +
 +    public interface ISQLSubscriberPlugin {
 +        public String processTableRow(String tableName, String action, String json, Map<​String,​ String> attributes);​
 +    }
 +
 +As you can see the API is very simple yet powerful. The API developer creates a single class which is called for each table row that's being inserted,​updated or deleted. The processTableRow java method is passed the name of the table which the row belongs to, the action being performed, the JSON or JavaScript Object Notation representing the name value pairs of the columns within the row, and a Map of any name, value pairs that are provided via configuration when the plugin is defined.
 +
 +The rules for using the API or Plugin are simple as well. The class is expected to return a valid JSON object structured as the original JSON back to the caller in the form of a String. The returned String will be evaluated as a JSON ojbect and if the evaluation fails then an error will be raised and the row will not be processed further, including being inserted into the target database table. The class should perform timely processing of the row. The processing of the row will not continue until the called method returns the JSON String.
 +
 +=== Enabling ​ a plugin ===
 +
 +The plugin or java class will need to be available when the replicator agent starts. The Replicator agent installation
 +creates a jars directory and the plugin class file must be contained within a valid java jar file which will need to
 +be copied into that folder. ​ Furthermore,​ you must explicitly configure the Replicator Agent to load and use the plugin.
 +
 +Here's an example:
 +
 +    <​task>​
 +        <​plugins>​
 +                <plugin max_column_value_size="​1024">​com.abc.replicator.plugins.SQLSubscriberTruncateColumnValue</​plugin>​
 +        </​plugins>​
 +    </​task>​
 +
 +The <​plugins>​ tag must be enclosed within the <​task>​ tag as show in the example. A single <​plugin>​ statement is used per plugin.
 +Each plugin is executed in the order defined in the configuration. This approach allows chainging of several plugins, where each
 +performs a specific task against the JSON String being manipulated. The attributes and associated values configured in the
 +<​plugin>​ tag will be made available to the plugin when it's processTableRow method is called. This can be useful for providing
 +static information to the plugin.
 +
 +So, in the example a single plugin will be enabled called com.abc.replicator.plugins.SQLSubscriberTruncateColumnValue. The class will
 +have a single entry in the attributes map whose key will be max_column_value_size,​ and the value will be 1024. The java class
 +uses the configured attributes to enssure that the value of each column does not exceed 1024 characters.
sql_agent_plugins.txt ยท Last modified: 2015/07/29 15:52 by mark.english