Technical Aspects of Interfaces
Interface tables and fields
Whenever a new interface is created an interface table (INTERFACE_[ID]) is created in the database. It holds a number of standard fields and, if needed, extra fields which are defined in two ways:
- File based interface: custom fields can be defined when creating the interface
- plugin based interface: the fields are fixed in the plugin itself. But exceptionally the plugin allows to create additional fields.
NOTE: in the database, an interface is defined as a record in the INTERFACES table. The setup of custom fields is stored in the XML of that interface.
Interface execution
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: new records are picked up from the Interface table and sent to the Plugin. The periodicity and the number of records can be configured. For each item processed, the Plugin gives back a result. For file based interfaces a file is created.
- Read (polling): 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 to 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.
To make this automated update possible, some prerequisites are mandatory:
- The interface needs to be used in a journey.
- One of the events defined in the ‘Events’ tab of the Interface properties must be used in the journey.
Example plugin code
The code below contains all steps required to create an interface which writes data into a Log file.
In order to facilitate the understanding, explanations are given before each code part:
publicclassSelligentLOG: IChannelModule, IChannelOutput
{
IChannelModulehas to be implemented in every Plugin because it handles the registration and the configuration of the Plugin within the CampaignAgent.
Four methods need to be defined into it:
#regionIChannelModule
IChannelHost m_Host;
publicboolCreate(IChannelHost Host,outString ErrorStr)
{
ErrorStr ="";
m_Host = Host;
Host.WriteLog("SelligentLOG plugin v1.0 created",false);
returntrue;
}
// Get Interface Info XML
publicboolGetConfigInterface(outString Xml,outString ErrorStr)
{
ErrorStr ="";
Xml ="";
Xml +="<XML GUID='32DD0A34-28B9-4DD2-81F2-3AF765A2F713' NAME='Selligent LOG Module' VERSION='1.0' DIRECTION='OUT' TYPE='LOG' CAPABILITIES='WRITE'>";
Xml +="<DESCRIPTION>Selligent Log module</DESCRIPTION>";
Xml +="<PARAMETERS>";
Xml +="</PARAMETERS>";
Xml +="<INTERFACE CONFIGURABLE='TRUE' DYNAMIC='FALSE'>";
Xml +="<FIELDS>";
Xml +="</FIELDS>";
Xml +="</INTERFACE>";
Xml +="</XML>";
Xml = Xml.Replace("'","\"");
returntrue;
}
-
GetDataInterface: allows to retrieve the plugin definition (fields and types) based on a defined set of configuration variables.
// Get Data Interface based on a certain configuration
publicboolGetDataInterface(String Config,outString Xml,outString ErrorStr)
{
ErrorStr ="Not implemented";
Xml ="";
returnfalse;
}
//validate the config.
publicboolValidateConfig(refString Config,outstringErrorStr)
{
ErrorStr ="Not ed";
returntrue;
}
#endregion
IChannelOutputreferences the output device.
Two methods are defined into it:
WriteData: sends the data to the plugin. They are sent as an XML document and can contain multiple records.
#regionIChannelOutput
// Write data towards the interface
publicboolWriteData(String Config,refString Xml,outString ErrorStr)
{
ErrorStr ="";
NetXmlDoc iConfigDoc =newNetXmlDoc();
NetXmlDoc iDataDoc =newNetXmlDoc();
if(iConfigDoc.LoadXml(Config) ==false)
{
ErrorStr ="Unable to parse Config XML";
returnfalse;
}
if(iDataDoc.LoadXml(Xml) ==false)
{
ErrorStr ="Unable to parse Data XML";
returnfalse;
}
Stream iStream = File.Open("c:\\temp\\myfile.txt", FileMode.Append);
StreamWriter iWriter =newStreamWriter(iStream);
if(iStream ==null)
{
ErrorStr ="Unable to open file";
returnfalse;
}
for(inti = 0; i < iDataDoc.GetRootNode().GetChildCount(); i++)
{
iWriter.WriteLine("RECORD");
NetXmlNode iNode = iDataDoc.GetRootNode().GetChild(i);
for(intc = 0; c < iNode.GetChildCount(); c++)
{
NetXmlNode Field = iNode.GetChild(c);
String Name = Field.GetAttribute("NAME");
String Content = Field.GetContent();
Content = Content.Replace("\n"," ");
iWriter.WriteLine(Name +":"+ Content);
iNode.SetAttribute("EXTID","P_"+ DateTime.Now.ToString("yyyyMMdd_HHmmss"));
}
}
iWriter.Flush();
iStream.Close();
Xml = iDataDoc.GetXml();
returntrue;
}
- ReadData: interrogates the plugin to check if new data are available. Those data are sent as an XML Document and can contain multiple records.
// Read data from the interface
publicboolReadData(String Config,refString Xml,outString ErrorStr)
{
ErrorStr ="Not ed";
returnfalse;
}
#endregion
}
Interface record states
1= pickup
2= in progress
10= error
20= batch: file was created but not yet send
25= wait feedback
30= success (executed)
35= feedback error: successfully processed but a feedback error has occurred
40= feedback
50= canceled
60= no handler: no handler was found (incomplete dispatch logic)
61= blocked by rule
