Treatment connectors
The treatment connectors framework allows developers to create their own connectors.
The framework gives a standard way of defining :
- an XML definition file: a configuration based on standard screen definition using sections and fields and the entry points within the Studio.
- a treatment connector editor class: dynamic behavior to edit the configuration properties.
- a treatment connector runtime class: class to use at runtime execution.
- an XML resource file: localized string.
Connector definition
A connector is a package of several connectors (treatments or services). Any connector included in this package use the same type of connection.
<connectors>
<connector name="mail" version="1.0" company="Visiativ Software" ref-connection="mail-connection">
...
</connector>
</connectors> A connector is defined with the following attributes:
- name: the system name of the connector. It should be unique on the Process Server;
- ref-connection: the connection reference attribute. It should be valid;
- version: the version of the connector;
- company: the company who developed the connector.
Treatment definition
Treatment connectors are part of the treatment elements available on the diagram library. They can be added to a diagram in a same way as the standard treatments (Field modifier, Role modifier, State modifier or Script).
XML definition file
The XML treatment connector definition file should be deployed on the custom/connectors folder. Its name must be unique on the Process server. To prevent name conflicts it is recommended to use the following template: companyName-connectorsType.xml (e.i. visiativ-education.xml). This XML definition file provides all the necessary information to describe a treatment connector:
- Treatment connector: it is defined with the following attributes:
- name: the system name of the treatment connector;
- execution: allows specifying if the connector is synchronous or asynchronous.
- useExternalDataConnection: gives the choice to the designer to either select a connection or use the default configuration of the Process server.
<connectors> <connector name="mail" ref-connection="mail-connection" version="1.0" company="Visiativ Software"> <treatments> <treatment name="sendMail" label="treatment.mail.sendMail" execution="asynchronous" useExternalDataConnection="false" > ... </treatment> </treatments> </connector> </connectors>
- Connector runtime class: the execution unit called while changing state on a process document.
- Connector configuration: a set of required fields to configure a treatment connector.
Runtime class
A runtime class is a Java class which will be called by the framework when a user changes the state of a process document. A runtime class must extend the com.axemble.vdoc.sdk.connectors.BaseTreatmentConnector class.
By creating a treatment connector runtime class you need to implement the following method:
execute(): the execute method receives the context of the user, the current process document (IWorkflowInstance) and the custom DOM element (retrieved from the XML configuration). The return value is an int value which can take one of the following values:IConnectorExecuteStatus.STOP,IConnectorExecuteStatus.CONTINUE,IConnectorExecuteStatus.STOP_ASYNCHRONOUS.
Three other methods could be overridden:
beforeCompletion(...): called just before committing the current transaction.afterCompletion(...): called just after either a commit or a rollback operation on the current transaction.asyncExecute(...): this method is called if the treatment connector has been set as an asynchronous treatment (set the execution attribute to asynchronous).
A runtime class is declared as follow:
<connectors>
<connector name="mail" ref-connection="mail-connection" version="1.0" company="Visiativ Software">
<treatments>
<treatment name="sendMail" label="treatment.mail.sendMail" execution="asynchronous" useExternalDataConnection="false" >
<class qualifiedName="com.axemble.vdoc.connectors.mail.MailTreatmentConnector" />Icons
This section allows developers to specify all necessary icons to be used within the diagram editor. Only two sizes are used at the moment :
- small size: 16 x 16 pixels;
- medium size: 24 x 24 pixels.
Be aware, if none icon is specified, default icons will be displayed by the Studio.
<connectors>
<connector name="mail" ref-connection="mail-connection" version="1.0" company="Visiativ Software">
<treatments>
<treatment name="sendMail" label="treatment.mail.sendMail" execution="asynchronous" useExternalDataConnection="false" >
<class qualifiedName="com.axemble.vdoc.connectors.mail.MailTreatmentConnector" />
<icons>
<icon name="small" path="treatments/sendmail_s.png" />
<icon name="medium" path="treatments/sendmail_m.png" />
<icon name="large" path="treatments/sendmail_l.png" />
</icons>Configuration definition
The configuration definition allows developers to specify a list of <field> tags the designer could use to properly configure a treatment connector. These fields can be categorized into <section> tags. To make the configuration more dynamic an editor class could be specified.
<configuration>
<class qualifiedName="com.axemble.vdoc.connectors.mail.MailTreatmentConnectorEditor" />
<section name="sender" label="treatment.mail.sendMail.section.sender">
<fields>
<field name="fldSenderChoices" label="..." ctrl="textselectlist" mode="write" throw-events="true"
string-value="fromCurrentContext">
<options>
<option key="fromCurrentContext" labelid="LG_FROM_CURRENT_CONTEXT"/>
<option key="fromField" labelid="LG_FROM_FIELD"/>
</options>
</field>
<field name="fldFrom" label="..." description="..." ctrl="selector" mandatory="true"
screen="Property" method="select" type="1" />
</fields>
</section>
<section name="recipients" label="treatment.mail.sendMail.section.recipients">
<fields>
<field name="fldRecipientsChoices" label="..." ctrl="textselectlist" mode="write" throw-events="true"
string-value="fromMailingList">Entry points
The Studio makes some of its screen parts available for including new features (workflow library). The <entry-points> tag allows developers to specify where a treatment will be included and how it will be categories within a specific screen part.
<entry-points>
<workflow-library categoryName="process" />
</entry-points>Editor class
An editor class is a Java class which allows developers to produce dynamic behaviors on the treatment connector configuration properties (XML definition file). An editor class must extend the com.axemble.vdoc.sdk.connectors.BaseConnectionEditor class.
The editor class works in the same way as the document or resource extensions. You can override the following standard methods:
init(): called at the instantiation time.onBeforeLoad(): called just before the screen is loaded on the server side.onAfterLoad(): called just after the screen is loaded on the server side.onBeforeSave(): called just before saving the document.onAfterSave(): called just after saving the document.
Specifically to treatment connector editor class, the connector Framework provides the following methods:
getCustomConfiguration(): returns the DOM element representing the custom tag within the configuration tag.getParentContext(): returns the current IWorfklow object as a IConnectorParentContextSupport.getResource(): allows to manipulate the document as a @IResource object.getResourceController(): allows to to interact with the user interface.getForm(): returns the current XMLForm screen.
An editor class is declared as follow:
<configuration>
<class qualifiedName="com.axemble.vdoc.connectors.mail.MailTreatmentConnectorEditor" /> XML resource
In order to localize the configuration and the error messages of the treatment to different languages, you should always specify each string as a resource. The XML resource file should be deployed on the custom/internationalization folder. Its name must be unique on the Process server. To prevent name conflicts it is recommended to use the following template: companyName-connectionType-resources.xml (e.i. visiativ-education-resources.xml). This file must contain every string used for the treatment.
<?xml version="1.0" encoding="UTF-8"?>
<res>
<id value="LG_STRING_EXAMPLE">
<lang value="fr" flag="0">Exemple de chaine de traduite</lang>
<lang value="en" flag="0">Translated string example</lang>
<lang value="de" flag="1">Übersetzes String Beispiel</lang>
</id>
</res>Create a treatment connector sending email
Create a category for a treatment connector
This file should be available deployed on the relative path WEB-INF\storage<custom><global>\education-global.xml.
<?xml version="1.0" encoding="UTF-8"?>
<definitions>
<connector>
<treatment>
<categories>
<category name="education" label="treatment.education.label" description="treatment.education.description" />
</categories>
</treatment>
</connector>
</definitions>Define a connector
This file should be available from the relative path WEB-INF\storage<custom><connectors>\education-smtp.xml within the final connectors package.
<?xml version="1.0" encoding="UTF-8"?>
<connectors>
<connector name="smtp.connector" version="1.0" company="Visiativ Software" ref-connection="smtp.connection">
<treatments>
</treatments>
</connector>
</connectors>Associate a category and the runtime class to the treatment connector
<?xml version="1.0" encoding="UTF-8"?>
<connectors>
<connector name="smtp.connector" version="1.0" company="Visiativ Software" ref-connection="smtp.connection">
<treatments>
<treatment name="sendMail" label="smtp.connector.sendMail.label" execution="asynchronous">
<class qualifiedName="com.axemble.education.connectors.smtp.SampleSendMailTreatmentConnector" />
</treatment>
</treatments>
</connector>
</connectors>Create the runtime class for the treatment connector
package com.axemble.education.connectors.smtp;
import org.w3c.dom.Element;
import com.axemble.vdoc.sdk.connectors.BaseTreatmentConnector;
import com.axemble.vdoc.sdk.interfaces.IContext;
import com.axemble.vdoc.sdk.interfaces.ITaskInstance;
import com.axemble.vdoc.sdk.interfaces.IWorkflowInstance;
public class SampleSendMailTreatmentConnector extends BaseTreatmentConnector {
private static final long serialVersionUID = -1412125636353912245L;
/* (non-Javadoc)
* @see com.axemble.vdoc.sdk.connectors.BaseTreatmentConnector execute(com.axemble.vdoc.sdk.interfaces.IContext, com.axemble.vdoc.sdk.interfaces.IWorkflowInstance, com.axemble.vdoc.sdk.interfaces.ITaskInstance, org.w3c.dom.Element)
*/
@Override
public int execute(IContext context, IWorkflowInstance workflowInstance, ITaskInstance taskInstance, Element customElement) {
return BaseTreatmentConnector.CONTINUE;
}
}Set the configuration of the treatment connector
<?xml version="1.0" encoding="UTF-8"?>
<connectors>
<connector name="smtp.connector" version="1.0" company="Visiativ Software" ref-connection="smtp.connection">
<treatments>
<treatment name="sendMail" label="smtp.connector.sendMail.label" execution="asynchronous">
<class qualifiedName="com.axemble.education.connectors.smtp.SampleSendMailTreatmentConnector" />
<configuration>
<class qualifiedName="com.axemble.education.connectors.smtp.SampleSendMailTreatmentConnectorEditor" />
<section name="main" label="smtp.connector.sendMail.section.main.label">
<fields>
<field
name="fldSubject"
label="smtp.connector.sendMail.subject.label"
description="smtp.connector.sendMail.subject.description"
ctrl="com.axemble.vdoc.sdk.document.fields.LocalizedTextField"
string-value="[${iWorkflowInstance-document.sys_Reference}] - ${iWorkflowInstance-document.sys_Title}"
mandatory="true" />
<field
name="fldBody"
label="smtp.connector.sendMail.body.label"
description="smtp.connector.sendMail.body.description"
ctrl="com.axemble.vdoc.sdk.document.fields.LightBoxField"
mandatory="true"
targetLabel="treatment.mail.sendMail.bodyContent.label">
<targetField
ctrl="fckeditor"
fck_ToolbarSet="EzsRichText"
fck_ImageBrowser="false"
fck_LinkBrowser="false"
fck_FlashBrowser="false" />
</field>
</fields>
</section>
<custom />
</configuration>
<entry-points>
<workflow-library categoryName="education" />
</entry-points>
</treatment>
</treatments>
</connector>
</connectors>Create the editor class for the treatment connector
package com.axemble.education.connectors.smtp;
import com.axemble.vdoc.sdk.connectors.BaseTreatmentConnectorEditor;
public class SampleSendMailTreatmentConnectorEditor extends BaseTreatmentConnectorEditor {
private static final long serialVersionUID = -6439184427515294832L;
public final static String FIELD_SUBJECT = "fldSubject";
public final static String FIELD_BODY = "fldBody";
@Override
public boolean onAfterLoad() {
// place your code here...
return super.onAfterLoad();
}
}