Novell Home

Action Development Guide

INTEGRATOR INTERACTION

In general, most Actions written under this template will work closely with another type of plug-in, the Integrator. The Integrator's function is to simplify protocol-level communications and put them into a reusable framework that the Actions can leverage more easily than if they had to implement a custom protocol each time. Available Integrators include File, Syslog, SNMP, SOAP, LDAP, and so on. Some Integrators are simple message handlers — construct a message and send it — and some are more complex query/response interfaces.

Integrator Configuration

As stated, the function of the Integrator is to create a simplified, reusable protocol handler. The idea is to boil down the complexities of working with a particular protocol into a small set of configurable options, and then let those options be configured by the implementor. Let's take SMTP for example: the SMTP Integrator handles the complexities of the SMTP protocol, retries, error handling, and that sort of thing automatically. The implementor simply needs to configure the target SMTP server and possibly authentication credentials, and that's about it.

Note that unlike with Collectors and Connectors, there's no explicit "chain" of components — like Event Source / Connector / Collector — but instead each Integrator is configured independently of any particular Action. As with Actions, each Integrator is a plug-in which can be imported into Sentinel, and each Integrator plug-in can then be configured one or more times as an Integrator instance with a different set of configuration parameters. You might configure a few different SMTP Integrators, for example, each with a different target SMTP server.

The set of configurable parameters varies for each Integrator is fully documented in each Integrator's documentation, available on the Plug-ins download site. In general each Integrator has a set of Basic Information parameters, which basically provide a name and description; a set of Configuration parameters, which reflect the custom configuration required for that particular Integrator (such as SMTP server and port, for SMTP); and finally one can also define additional ad hoc Integrator Properties, which just assign some name-value pair properties to that instance of the Integrator that can be looked up elsewhere.

Finding Integrators From Actions

Actions need to identify which Integrator to use so that a connection to that Integrator can be initialized. There are basically two methods by which this can be done:

  • Explicit configuration: The Action can be configured with a parameter that, at Action instance configuration time, allows the user to select from the current set of configured Integrator instances from a dropdown list. The name of the selected Integrator is passed to the Action, and is used to look up the correct Integrator.
  • Property search: Rather than explicitly configuring a specific Integrator to use, the Action can instead search for an Integrator with a particular property setting. For example, an Action that just needs to send e-mail but doesn't really care by what channel can search for the SentinelDefaultEmailServer property, and use that Integrator.

These two methods are implemented slightly differently. The first method is quite simple, since the Action already has the name of the exact Integrator to use. All you need to do is:

this.integrator = new IntegratorInstance();

The second method is slightly more complex, since you need to handle the case where there's more than one Integrator instance with the desired property, or the case where there is none. You'll need to do something more like:

var integrators = Integrator.forProperty("SentinelDefaultEmailServer", "true");
if((integratorsForProperty == null) || (integratorsForProperty.length < 1)) {
    return false;
}

this.integrator = {}; 
this.integrator.handle = integrators[0]; // Select only the first matching Integrator
this.integrator.api = this.integrator.handle.getAPI();

The end result of the above code either way is that you'll end up with a single Integrator instance in this.integrator. Note that this object has a "handle" to the integrator in this.integrator.handle, and a pointer to the Integrator API in this.integrator.api (the IntegratorInstance constructor handles this for you).

Using the Integrator API

Each Integrator defines its own API, with varying degrees of complexity. The various API methods will be available in the this.integrator.api object, but what specifically they are you will have to look up in the associated Integrator documentation. We'll provide some examples here to illustrate:

SMTP Integrator

The SMTP Integrator defines the API method send() which sends an e-mail. You would do something like this:

integrator.api.send("Sentinel@netiq.com", "This is an important e-mail", "The body of the e-mail says this");
File and Syslog Integrators

These two Integrators define a simple log() method which dumps a line of data to a file or to a syslog target, respectively. Usage is simply:

this.integrator.api.log("This is a line of data");
SOAP Integrator

This one is more complicated, because a SOAP "message" has to be constructed according to a specific WSDL. You might end up with something like this:

var paramTypes = ["java.lang.String []"].toJava(java.lang.String);
var paramValues = [javastringarray].toJava(java.lang.Object);
var stringarray = instance.integrator.handle.constructObject("com.novell.soa.af.impl.soap.StringArray", paramTypes, paramValues);
paramTypes = ["java.lang.String", "com.novell.soa.af.impl.soap.StringArray"].toJava(java.lang.String);
paramValues = ["reason", stringarray].toJava(java.lang.Object);
var dataitem = instance.integrator.handle.constructObject("com.novell.soa.af.impl.soap.DataItem", paramTypes, paramValues);
var classType = instance.integrator.handle.classForName("com.novell.soa.af.impl.soap.DataItem");
var javadataitemarray = [dataitem].toJava(classType);
paramTypes = ["com.novell.soa.af.impl.soap.DataItem []"].toJava(java.lang.String);
paramValues = [javadataitemarray].toJava(java.lang.Object);
var dataitemarray = instance.integrator.handle.constructObject("com.novell.soa.af.impl.soap.DataItemArray", paramTypes, paramValues);
var retval = instance.integrator.api.start(instance.PARAMS.workflow, this.LDAPDN, dataitemarray);

Action Development Guide

© 2014 Novell