User Tools

Site Tools


sql_agent_plugins

The SQL Subscriber Plugin Framework

The Plugin support described here is provided only when using the SQLSubscriber handler.

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