Connections

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 Process server. To prevent name conflicts it is recommended to use the following template: companyName-connectionType.xml (e.i. visiativ-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 Process server. The category attribute allows to group several types of connections. The category appears on the first page of the connection creation wizard. 
    <connections>	
    <connection-settings name="mail-connection" category="mail">
        ...
    </connection-settings>
</connections>
  • 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 follows:

<connections>
	<connection-settings name="mail-connection" category="mail">
		<class qualifiedName="com.axemble.vdoc.connectors.mail.MailConnection" />

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.

<configuration>
	<class qualifiedName="com.axemble.vdoc.connectors.mail.MailConnectionEditor" />
	<section name="settings" label="LG_SETTINGS">
		<fields>					
			<field name="fldMailBaseUrl" label="LG_..." ctrl="text" />
			<field name="fldSmtpServer" label="LG_.." ctrl="text" mandatory="true" />
			<field name="fldSmtpPort" label="LG_..." ctrl="text" mandatory="true" />
			<field name="fldMailAdministrator" label="LG_..." ctrl="text" />
			<field name="fldMailSender" label="LG_..." ctrl="text" />
		</fields>
	</section>
</configuration>

Editor class

An editor class is a Java class which allows developers to produce dynamic behaviors on the connection configuration properties (XML definition file). It 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 interacting with the user interface.
  • getSheet(): returns the current XMLSheet screen.

An editor class is declared as follows:

<configuration>
	<class qualifiedName="com.axemble.vdoc.connectors.mail.MailConnectionEditor" />

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 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 connection.

<?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 connection

Create a category for a connection

This file should be available from the relative path WEB-INF\storage<custom><global>\education-global.xml.

<?xml version="1.0" encoding="UTF-8"?>
<definitions>
	<connector>
		<connection>
			<categories>
				<category name="education" label="connection.education.label" description="connection.education.description"/>
			</categories>
		</connection>
	</connector>
</definitions>

Define a connection

This file should be available from the relative path WEB-INF\storage<custom><connections>\education-mail.xml within the final connectors package.

<?xml version="1.0" encoding="UTF-8"?>
<connections>   
	<connection-settings name="smtp.connection" category="education">
	</connection-settings>                          
</connections>

Associate a category and the runtime class to the connection

<?xml version="1.0" encoding="UTF-8"?>
<connections>   
	<connection-settings name="smtp.connection" category="education">
		<class qualifiedName="com.axemble.education.connectors.smtp.SampleSMTPConnection" />
	</connection-settings>                          
</connections>

Create the runtime class for the connection

Two methods have to be implemented:

  • getConnection(): should return either an object or a structure which contains all the useful information to connect to the external system;
  • validate(): tests the connection.
package com.axemble.education.connectors.mail;

import com.axemble.vdoc.sdk.connectors.BaseConnection;

public class MailConnection extends BaseConnection {
    private static final long serialVersionUID = 8575257148794814192L;

    /* (non-Javadoc)
     * @see com.axemble.vdoc.sdk.connectors.BaseConnection#validate()
     */
    @Override
    public boolean validate() throws Exception {
        return true;
    }

    /* (non-Javadoc)
     * @see com.axemble.vdoc.sdk.connectors.BaseConnection#getConnection()
     */
    @Override
    public Object getConnection() {
        return null;
    }
}

Set the configuration and the editor class of the connection

<?xml version="1.0" encoding="UTF-8"?>
<connections>   
	<connection-settings name="smtp.connection" category="education">
		<class qualifiedName="com.axemble.education.connectors.smtp.SampleSMTPConnection" />
		<configuration>
			<class qualifiedName="com.axemble.education.connectors.smtp.SampleSMTPConnectionEditor" />
			<section name="settings" label="LG_SETTINGS">
				<fields>                                        
					<field name="fldMailBaseUrl" label="LG_MAIL_BASE_URL" ctrl="com.axemble.vdp.ui.core.document.fields.TextBoxField" />
					<field name="fldSmtpServer" label="LG_SMTP_SERVER" ctrl="com.axemble.vdp.ui.core.document.fields.TextBoxField" mandatory="true" />
					<field name="fldSmtpPort" label="LG_SMTP_PORT" ctrl="com.axemble.vdp.ui.core.document.fields.TextBoxField" mandatory="true" />
					<field name="fldMailAdministrator" label="LG_SMTP_MAIL_ADMINISTRATOR" ctrl="com.axemble.vdp.ui.core.document.fields.TextBoxField" />
					<field name="fldMailSender" label="LG_SMTP_MAIL_SENDER" ctrl="com.axemble.vdp.ui.core.document.fields.TextBoxField" />
				</fields>
			</section>
		</configuration>
	</connection-settings>                          
</connections>

package com.axemble.education.connectors.mail;

import com.axemble.vdoc.sdk.connectors.BaseConnectionEditor;

public class MailConnectionEditor extends BaseConnectionEditor {
    private static final long serialVersionUID = -8506977980390428675L;
}