Plugin Based Interfaces

Plugin-based interfaces are based on a DLL that contains a set of functions to manage interactions with external solutions. Data is either transferred to the plugin (outbound) or from the plugin (inbound).

A plugin interface is mostly defined in the DLL itself (login details, locations, parameters, etc)

Install the Plugin on the server

All Plugins have to be placed in the ‘agents/modules’ folder present on the application server. The CampaignAgent is in charge of managing the list of Plugins displayed in the Interface properties.

NOTE: When installing a new Plugin, the CampaignAgent needs to be restarted in order to take it into account.

Technical information on installed Plugins can also be retrieved from the database via the following query:

SELECT * FROM interface_plugins

Here is an example of the content of the ‘INTERFACE_PLUGINS’ table:

NOTE: The field ‘GUID’ is used as a unique identifier for each interface

 

Execution modes of Plugin Interfaces can be ‘instant’ or ‘scheduled’. Instant means after a user trigger. Scheduled means that the interface is executed when the journey is activated. Both modes always insert records into the interface table with field values as set in the interface. The Plugin is never executed directly.

Three standard operations characterize a Plugin interface:

  • Write (WRITEDATA method): new records are picked up from the Interface table and sent to the Plugin. New records from the interface table are transformed into an XML which is then interpreted by the WRITEDATA method. The periodicity and the number of records can be configured. For each item processed, the Plugin gives back a result.
  • Read (polling with READDATA method): read operations are executed in two situations and the output is always an update of the Interface table.
    • First situation - Outbound Plugin: the read routine is called and asks the Plugin for updates on items already sent to it. For each updated element, the Plugin returns a CQID and using this CQID, the interface requests data and stores them into the Interface table.
    • Second situation - Inbound Plugin (e.g. incoming The) : For this type of plugin, new records are not created based on the scheduling of the journey but on the data returned by the plugin. The read routine is called and asks the Plugin for new incoming items. In this case, data are automatically returned to the Interface because no CQID are available.
  • Processing: processing of feedback is done by the Campaign Agent. It checks if there are events to be triggered in the journey for every record that has a CHANGED value =1. After an event is executed, the CHANGED field is set to 0.

Creating the interface

Interfaces are created from the Process entry/Interface tab in Selligent Campaign.

To create a new Plugin based Interface, select the option 'New Plugin Interface' from the toolbar of the 'Interface' tab:

The following window is displayed:

Note that not all properties are configurable in here. Some properties are defined within the selected plugin and can only be viewed.

General

  • Name
  • Description:
  • Interface Module: choose the module that will be used to execute this interface. The version and type are automatically filled out when a plugin is selected.
  • Scheduling: set the time interval between 2 executions and the maximum batch size.

Technical note
The modules that are available for selection in this list, are all created by Selligent. These modules are in fact dll’s that contain the necessary information to enable an interaction between Selligent and the external application.
When no module is selected, there is no direct interaction with the external application but information is stored in special Interface tables which can be interrogated by the external application after attributing access rights to these tables.

 

When creating a new Plugin interface, it’s possible to configure specific parameters within the Plugin by clicking the ‘Configure’ button:

Example for the 'X' (formerly Twitter) direct message plugin:

The content of the window displayed depends on the inner definition of the Plugin. Here is an example based on an 'X' (formerly Twitter) module:

All data specified for the Plugin configuration are stored with the interface properties. This means that the same Plugin can be used in multiple interfaces with, for each, different parameter values.

The ‘Validate’ button triggers the validation of the defined configuration.

Technically, this validation creates a new record in the ‘INTERFACE_PLUGIN_REQUESTS’ table. Then, the CampaignAgent polls this table and executes requested operations. The validation is therefore an asynchronous process.

 

Fields

In the 'Fields' tab additional parameters can be specified. These parameters can be used to store information that is not stored directly on the contact's profile.

Most plugins fix the fields to be used in the interface table; in that case the interface definition is not dynamic and not configurable. The user is unable to change fields and the ‘Static definition’ indicator appears.

Following is an example of fields defined in the dll used by the SMS module. The fields cannot be edited.

NOTE: Parameters can only be defined in here when ‘No module’ has been selected on the‘General’tab. When a specific module is selected, the parameters are defined within the corresponding dll and are displayed automatically on the 'Fields' tab. They can not be edited.

 

When the field definition is not fixed in the DLL, two alternatives are available:

  • Configurable: The user is free to add fields to the interface using the ‘Add Parameter’ button.
  • Dynamic: All fields depend on the defined configuration. In this situation, an additional callback is performed after the configuration to retrieve the list of fields from the external system.

NOTE: Like file based interfaces, Plugin interfaces use the ‘CQID’ field to identify records. As this field is managed by Selligent system, it is not displayed in the interface configuration.

 

Following functionality is available in the 'Fields' tab:

  • Delete
  • Add parameter
  • Properties: view/edit a selected parameter

An interface can also be limited to a specific Audience list. The drop down list at the bottom of the window allows the selection of the required list.

 

Creating or editing a parameter displays its ‘properties’:

The following information can be defined:

  • Name
  • Type: type of the parameter (Text, Long Text, Numeric, Date Time)
  • Length: length of the parameter-field
  • Description: optional description of the parameter
  • Direction: direction of the data (Output, Feedback, Both)
  • Required: mandatory field or not
  • Field options: select an existing Optionlist if required

 

Events

Before being able to create events, the interface must be created first!

Define feedback events and assign a flag.  These events can be used in the journey after an interface component. Define constraints and specify the activation method.

  1. To add a new feedback event, press the ‘New’ button:


  2. Enter a name and description for the feedback event.
  3. Select the event that triggers the feedback. Following options are available:
      • The interface was executed.
      • An error occurred during interface execution
      • Feedback was received
      • Feedback was not received
  4. Select the icon to be displayed in front of the feedback:
  5. Finally, validate the creation by clicking the ‘OK’ button. The new feedback is added to the list.

NOTE: Feedback for an interface can be received via either a file that is imported (manually or automatically) of via the individual API.  

 

Using the plugin interface in a journey

A Plugin is composed by a set of C# class libraries regrouped in DLL files which can be used in one or more interfaces.

Each plugin is different. Depending on the type of plugin, different properties need to be defined when the plugin based interface is used in a journey.

Following is an example of an 'The out' interface used in a journey.

The Outbound The interface is added through drag and drop from the Interfaces folder in the tree view on the left. Double click the component to set the properties:

  • Mobile number & operator: Select the values for the mobile number and operator from the Audience list or linked list. Operator is optional.
  • Message: Contains the data for the SMS, including the text inserted into the SMS. Note that both can contain personalization fields. The icon next to the 'Message' field gives access to an editor allowing the composition of the message. A preview of the message is available from the editor.

NOTE: It is possible to use personalization fields in the message, just like in emails. The number where responses need to be sent to depends on the mobile provider.

  • Scheduling Method: Two scheduling methods can be used:  Instant Message and Scheduled message. This behavior is the same as the one used for email broadcasting.
  • Feedback: Information on each sent The is stored in a session table. When an inbound The is received the table is scanned to identify the contact from whom the answer is received. (Consult the ‘The Dialog’ topic get more information on The inbound management)

(Check out the SMS component for more details on the configuration)

  • Advanced tab: If multiple SMS out interfaces are defined, it is possible to switch from one interface to another.

When the above journey is executed, one record per contact in the selection is inserted in the interface table. The processing of the records in this interface table will then depend on the setup of the interface.

Here is a sample of code used to define a Plugin:  
publicboolWriteData(StringConfig,refStringXml,outStringErrorStr)
{
 ErrorStr ="";
 StringServer, Login, Pwd;
 if(ParseConfig(Config,outServer,outLogin,outPwd,refErrorStr) ==false)
    returnfalse;
 m_Host.WriteLog("SmsGateway: Server ["+ Server +"], Login["+ Login +"], Pwd ["+ Pwd +"]",false);
 NetXmlDoc iDoc =newNetXmlDoc();
 if(iDoc.LoadXml(Xml) ==false)
 {
   ErrorStr ="Unable to parse instruction xml";
   returnfalse;
 }
 NetXmlNode RecordsNode = iDoc.GetRootNode();
 for(inti = 0; i < RecordsNode.GetChildCount(); i++)
 {
NetXmlNode RecordNode = RecordsNode.GetChild(i);
       StringNumber ="", Network ="", Content ="";
for(intn = 0; n < RecordNode.GetChildCount(); n++)
       {
         NetXmlNode ValueNode = RecordNode.GetChild(n);
  StringName = ValueNode.GetAttribute("NAME");
         StringValue = ValueNode.GetContent();
  if(Name =="NUMBER") Number = Value;
  if(Name =="NETWORK")Network = Value;
         if(Name =="CONTENT")Content = Value;
}
 m_Host.WriteLog("Sending: Network ["+ Network +"], Number ["+ Number +"], Content ["+ Content +"]",false);
 RecordNode.SetAttribute("EXTID","1");
}
 Xml = iDoc.GetXml();
 returntrue;
}