Connections framework

The Connections framework allows developers to create their own connections to external systems.

Administrators can define, edit, and delete connections through the administration section.

The Connection Framework gives a standard way of defining :

  • an XML definition file: a configuration based on standard screen definition using sections and fields.
  • a connection editor class: dynamic behavior to edit the configuration properties.
  • a connection runtime class: class to use by the connectors.
  • an XML resource file: localized string.

Connection definition

Connections are available on the administration section. Administrators can therefore manage control access to connections.

XML definition

The XML connection definition file should be deployed on the custom/connections folder. Its name must be unique on the VDoc server. To prevent name conflicts it is recommended to use the following template: companyName-connectionType.xml (e.i. vdoc-education.xml). This XML definition file provides all the necessary information to describe a connection:

  • Connection name and its category: The name should be unique on the VDoc server. The category attribute allows to group several types of connections. The category appears on the first page of the connection creation wizard. 
    Error during retrieving content skip as ignoreDownloadError activated.
  • Connection runtime class: The execution unit called while requesting the connection.
  • Connection configuration: A set of required fields to configure a connection.

Runtime class

A runtime class is a Java class which will be called by the framework when an administrator clicks on the Validate button or at runtime level while a user changes the state of a workflow. A runtime class must extend the com.axemble.vdoc.sdk.connectors.BaseConnection class.

By creating a connection runtime class you need to implement two methods:

  • getConnection(): must return either a real connection such as a java.sql.Connection object or a specific object which contains all the necessary information to connect to the external system. The return value is an java.lang.Object.
  • validate(): allows to validate the connection. Most of the time this method should call the getConnection() method.

Two other methods could be overridden:

  • getSuccessMessage(...): Allows to override the message to display when connection test succeeds.
  • getErrorMessage(): Allows to override the message to display when the connection test fails.

A runtime class is declared as follow:

Error during retrieving content skip as ignoreDownloadError activated.

Configuration definition

The configuration definition allows developers to specify a list of <field> tags the administrator could use to properly configure a connection. 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.

Editor class

An editor class is a Java class which allows developers to produce dynamic behaviors on the connection configuration properties (XML definition file). An editor class must extend the com.axemble.vdoc.sdk.connectors.BaseTreatmentConnectorEditor 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 connection editor class, the connection Framework provides the following methods:

  • getCategoryName(): returns the name of the associated connection category.
  • getCustomConfiguration(): returns the DOM element representing the custom tag within the configuration tag.
  • getResource(): allows to manipulate the document as a @IResource object.
  • getResourceController() : allows to to interact with the user interface.
  • getSheet(): returns the current XMLSheet screen.

An editor class is declared as follow:

Error during retrieving content skip as ignoreDownloadError activated.

XML resource

In order to localize the configuration of the error connection 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 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 connection.

Error during retrieving content skip as ignoreDownloadError activated.