Treatment connectors framework

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.

Error during retrieving content skip as ignoreDownloadError activated.

A connector is defined with the following attributes:

  • name: The system name of the connector. It should be unique on the VDoc 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 VDoc server. To prevent name conflicts it is recommended to use the following template: companyName-connectorsType.xml (e.i. vdoc-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 to specify if the connector is synchronous, asynchronous or background. background value implies the execution will run in a separate Thread and the current execution will wait until the thread ends;
    • useExternalDataConnection: gives the choice to the designer to either select a connection or use the default configuration of the VDoc server. 
      Error during retrieving content skip as ignoreDownloadError activated.
  • 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:

Error during retrieving content skip as ignoreDownloadError activated.

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.

Error during retrieving content skip as ignoreDownloadError activated.

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.

Error during retrieving content skip as ignoreDownloadError activated.

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.

Error during retrieving content skip as ignoreDownloadError activated.

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:

Error during retrieving content skip as ignoreDownloadError activated.

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 VDoc server. To prevent name conflicts it is recommended to use the following template: companyName-connectionType-resources.xml (e.i. vdoc-education-resources.xml). This file must contain every string used for the treatment.

Error during retrieving content skip as ignoreDownloadError activated.