Packaging

This chapter contains packaging task SDK documentation and samples.

The Packaging class offers SDK openings for deploying your solutions with more flexibility.

How it works

In an XML file, you define calls to Java extensions. The extension’s call can be launched :

at startup of Process server, see <startup> element.
when you install a new instance of Process (first startup), see <install> element.
for a migration (from version A to version B), see <migration> element.

Packaging definition

XML definition file

The XML packaging definition file must be deployed on the custom/packaging folder. Its name must be unique on the Process server. This XML definition file provides all the necessary information to launch the extension.

The packaging element

The packaging element can contain the following children elements :

Element	Description
name	the name of the application, ex: Process.
version	the current version of the application.
startup	it’s used to launch the extension at every startup of Process.
install	it’s used to launch the extension for a new installation.
migration	it’s used to launch the extension during a migration.

XML example:

<packaging>
    <name>myApp</name>
    <version>1.0</version>
    <startup>...</startup>
    <install>...</install>
    <migration>..</migration>
</packaging>

Process :

In Process, the migration tasks are not cumulative.

The rules for writing migration tasks are the following:

In the case of a minor to another minor of the same major (ex: migration 17.0 to 17.2) :

the migration tasks are carried over from the previous versions to the previous major

Indeed, the current rule allows to skip intermediate minor versions. So we need to execute the migration tasks of all the intermediate minors during a version jump.

    <!-- from 17.0 -->
<migration fromVersion="11.0" fromSP="SP0">
	<extension name="com.axemble.vdoc.update.migration.v17.AddSQLColumnToHistoryTablesExtension"/>
	<extension name="com.axemble.vdoc.update.migration.v17.BaseUrlMigrationExtension"/>
</migration>

	<!-- from 17.1 -->
<migration fromVersion="11.0" fromSP="SP1">
    <extension name="com.axemble.vdoc.update.migration.v17.BaseUrlMigrationExtension"/> <!-- This task has been carried over to the migration from 17.0  -->
</migration>

In the case of the last minor of a major to a major (ex: migration 17.2 to 18.0):

we do not carry over the tasks.

Indeed, the current rule imposes to have installed in the last minor version to move to the next major version. By starting from the last minor version and applying the previous rule, we make sure that all the necessary tasks have been executed. In this case, we control the versions of departure and arrival of the migration (last minor of the major N towards the first minor of the version N+1)

	<!-- from 17.2 -->
<migration fromVersion="11.0" fromSP="SP2">
    <extension name="com.axemble.vdoc.update.migration.v18.MigrateMailStyleAndFormExtension" critical="true"/>
    <extension name="com.axemble.vdoc.update.migration.v18.EasysitePluginDeletionExtension" critical="true">
        <param name="plugin" value="sys.forum"/>
    </extension>
    <extension name="com.axemble.vdoc.update.migration.v18.EasysitePluginDeletionExtension" critical="true">
        <param name="plugin" value="sys.news"/>
    </extension>
    <extension name="com.axemble.vdoc.update.migration.v18.PortletTypeDeletionExtension" critical="true"/>
    <extension name="com.axemble.vdoc.update.migration.v18.AddWarningInformationForAgent" critical="true"/>
</migration>

	<!-- from 18.0 -->
<migration fromVersion="12.0" fromSP="SP0">
    <extension name="com.axemble.vdoc.update.migration.v18.DeleteCMISAndSharepointConnectorMigrationExtension" critical="true"/>
    <extension name="com.axemble.vdoc.update.migration.v18.FixDelegationDynamicTableLabelMigrationExtension" critical="true"/>
</migration>

Import :

In Process, the import tasks are not cumulative.

As an application can be imported from any version, the new import tasks must be carried over to all previous versions

Example : On the oldest import supported version, you can find all the tasks up to the current version

<import fromVersion="10.0" fromSP="SP0">
    <extension name="com.axemble.vdoc.update.migration.v2012.process.MigrateProcessXMLFormsExtensions" />
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateLayoutCssClassExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2012.process.MigrateFormulasFunctionsExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v2011.process.WorkflowSubFormCleanSysNameExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v2011.process.InheritedFormExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v2012.process.MigrateRoleTreatmentTaskExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2012.process.CleanConnectorTreatmentTaskExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2012.ViewDefinitionExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2012.connector.SharePointConnectorMigrationExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2012.process.FixPropertiesExtension" />
    <extension name="com.axemble.vdoc.update.process.RestoreFormDescriptionExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v2014.PropertyAliasMigrate" />
    <extension name="com.axemble.vdoc.update.migration.v2012.process.FixFieldTreatmentTaskExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateFormDefinitionWorkflowTableExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateWorkflowContainerFieldsExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateServiceOutputValueDefinition" />
    <extension name="com.axemble.vdoc.update.migration.v2014.RemoveSearchSortExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v15.OrderActionsByTasks"/>
    <extension name="com.axemble.vdoc.update.migration.v15.RewriteSQLConnectorOutputParameters"/>
    <extension name="com.axemble.vdoc.update.migration.v15.FixDBFileCascadeDeleteExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v17.ConvertFileInputAdditionalParametersExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v18.ImportAppMailStyleAndFormExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v18.DeleteCMISAndSharepointConnectorImportExtension"/>
</import>


	<!-- 14.0 -->
<import fromVersion="10.0" fromSP="SP1">
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateLayoutCssClassExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2012.ViewDefinitionExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2012.process.FixPropertiesExtension" />
    <extension name="com.axemble.vdoc.update.process.RestoreFormDescriptionExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v2014.PropertyAliasMigrate" />
    <extension name="com.axemble.vdoc.update.migration.v2012.process.FixFieldTreatmentTaskExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateFormDefinitionWorkflowTableExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateWorkflowContainerFieldsExtension" />
    <extension name="com.axemble.vdoc.update.migration.v2014.MigrateServiceOutputValueDefinition" />
    <extension name="com.axemble.vdoc.update.migration.v2014.RemoveSearchSortExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v15.OrderActionsByTasks"/>
    <extension name="com.axemble.vdoc.update.migration.v15.RewriteSQLConnectorOutputParameters"/>
    <extension name="com.axemble.vdoc.update.migration.v15.FixDBFileCascadeDeleteExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v17.ConvertFileInputAdditionalParametersExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v18.ImportAppMailStyleAndFormExtension"/>
    <extension name="com.axemble.vdoc.update.migration.v18.DeleteCMISAndSharepointConnectorImportExtension"/>
</import>

Add-on

Since Process18.0.0, the option “cumulative” has been added to the add-on packaging tasks. It allows, when set to “true”, to cumulate the migration tasks in case of version skip. So, it is not necessary to carry over the new tasks on each previous version.

Since Process2024.1.0, attributes have been added to trigger migrations based on a migration start version range. A range start version of the add-on to be migrated is declared in the fromStart attribute, and a range end version in the fromEnd attribute. If the migrated add-on has a pre-migration version between fromStart and fromEnd, the extension will be executed.

Example : For a migration from version 1.0, extensions 1, 2, 3, 6 and 7 will be executed.

<migration fromStart="1.0" fromEnd="3.0">
    <extension name ="com.visiativ.addon.migration.MigrationExtension1" critical="true"/>
</migration>

<migration from="1.0" cumulative="true">
    <extension name ="com.visiativ.addon.migration.MigrationExtension2" critical="true"/>
</migration>

<migration from="2.0" cumulative="true">
    <extension name ="com.visiativ.addon.migration.MigrationExtension3" critical="true"/>
</migration>

<migration from="2.0">
    <extension name ="com.visiativ.addon.migration.MigrationExtension4" critical="true"/>
</migration>

<migration fromStart="2.0" fromEnd="3.0">
    <extension name ="com.visiativ.addon.migration.MigrationExtension5" critical="true"/>
</migration>

<migration fromStart="0.5" fromEnd="2.0">
    <extension name ="com.visiativ.addon.migration.MigrationExtension6" critical="true"/>
</migration>

<migration from="1.0">
    <extension name ="com.visiativ.addon.migration.MigrationExtension7" critical="true"/>
</migration>

The extension element

It’s a child element for the startup, install and migration elements. It defines the developed extension that will be executed.

The extension element contains the following attributes:

Attribute	Description
name	the class name.
runOnce	used with startup element, it launches the extension once.
critical	if a critical error occurs, the startup is stopped.

XML example:

<packaging>
    <startup>
        <extension name="Class Extension Name" runOnce="true or false"/>
    </startup>
    <install>
        <extension name="Class Extension Name" critical="true or false"/>
    </install>
    <migration>
        <extension name="Class Extension Name"/>
    </migration>
</packaging>

The param element

The param element is a child of the extension element. It’s used to pass parameters to the developed extension.

The param element contains the following attributes:

Attribute	Description
name	the name of the parameter.
value	the value of the parameter.

XML example:

<packaging>
	<startup>
		<extension name="Class Extension Name" runOnce="true or false">
			<param name="Name of parameter 1" value="Value of parameter 1"/>
			<param name="Name of parameter 2" value="Value of parameter 2"/> 
		</extension>
	</startup>
	<install>
		<extension name="Class Extension Name" critical="true or false">
			<param name="Name of parameter 1" value="Value of parameter 1"/> 
		</extension>
	</install>
</packaging>

Runtime class

A runtime class is a Java class that will be called by the framework at the startup of Process. A runtime class must extend the com.axemble.vdoc.sdk.packaging.extensions.BaseTaskExtension class.

By creating a packaging runtime class you need to implement the execute() method:

execute(): The execute method receives one parameter of type java.util.Map<key,value>.

A runtime class is declared as follows:

public class LaunchCmdTaskExtension extends BaseTaskExtension {
    /**
     * @see com.axemble.vdoc.sdk.packaging.extensions.BaseTaskExtension execute(java.util.Map)
     */
    @Override
    protected void execute(Map<String, String> parameters) throws Exception {
        String command = parameters.get("Name of the parameter");
        // ...
    }
}

Example

The following example shows how to mount a network drive at startup of Process.

XML definition file

<?xml version="1.0" encoding="ISO-8859-1"?>
<packaging>
    <name>myApp</name>
    <version>1.0</version>
    <startup>
        <extension name="com.axemble.vdoc.xxx.task.LaunchCmdTaskExtension" critical="false" runOnce="false">
            <param name="command" value='net use I: \\vdoc-storage\client\ "password" /USER:LYON\administrator /PERSISTENT:YES'/>
        </extension>
    </startup>
</packaging>

Runtime class definition

public class LaunchCmdTaskExtension extends BaseTaskExtension {
    /** the default class logger */
    private static final com.axemble.vdoc.sdk.utils.Logger LOG = com.axemble.vdoc.sdk.utils.Logger.getLogger(LaunchCmdTaskExtension.class);

    /**
     * @see com.axemble.vdoc.sdk.packaging.extensions.BaseTaskExtension execute(java.util.Map)
     */
    @Override
    protected void execute(Map<String, String> parameters) throws Exception {
        String command = parameters.get("command");
        Runtime.getRuntime().exec(command);
    }
}

Running the task by programming

It’s possible to run the LaunchCmdTaskExtension task by programming using the executeTask() method:

Map<String,String> parameters= new HashMap<>();
parameters.put("command", "val1");

portalModule.executeTask( LaunchCmdTaskExtension.class, parameters );