Workflow

Definition elements

When a process is generated, several elements are implanted in the database. From these definition elements we will keep the following:

  • IProject: corresponds to the application;
  • ICatalog: corresponds to a catalog of the project. It groups every process;
  • IWorkflowContainer: constitute the process. It groups every process versions.
  • IResourceDefinition: it groups all the properties (tasks and document fields) defined in the process via the web designer;
  • IProperty: description of a process field;
  • IWorkflow: constitutes the process description as a graph. Gathers the tasks,the actions and the roles.
  • ITask: description of a manual task;
  • IAction: description of an action;
  • IRole: role representative.

Diagram of definition elements classes

This classes’ diagram represents the main relations that exist between every classe of the process system.

classDiagram IProject o-- ICatalog : 1 - * IProject : IConfiguration configuration ICatalog --> IExternalReference : 1 --> * ICatalog : IConfiguration configuration IExternalReference <|-- IJdbcReference IExternalReference <|-- IDataSourceReference ICatalog *-- IList : 1 - * IList <|-- IXMLList IList <|-- IStringList ICatalog o-- IProperty : 1 - * IProperty --o IResourceDefinition : * - 1 ICatalog o-- IWorkflowContainer : 1 - * IWorkflowContainer o--> IResourceDefinition : 1 - * IWorkflowContainer o-- IWorkflow : 1 - * IWorkflow o-- IForm : 1 - 1..1 IWorkflow *-- ITask : 1 - * ICatalog o-- IRole : 1 - * IRole <--* IWorkflow : 1 - * IRole <--o ITask : 1 - 1..1 ITask o-- IForm : 1 - * IForm <|-- IMailForm ITask *-- IAction : 1 - *

Table of definition elements correspondence

Functional term Technical term SDK term EJB term (prefix:ejb/com/axemble/vdp/) Description
Application Project IProject Project An application is a group of catalogs and data universe.
Catalog Catalog ICatalog Catalog A catalog is a group of processes and associated documents.
Resource template Resource template IResourceDefinition Resource template
Field, property Property IProperty Property Element constituting the description of a value supported by the document.
Process Process version group IWorkflowContainer VersionGroup Group of process versions which share properties, views and roles.
Process version, workflow Process version IWorkflow TreatmentClass A process is the modelling of the document path through multiple stages. It can also call sub-processes.
Task, stage Step ITask Stage A task is the modeled object identifying a process stage.
Workflow action, user action, routing action Routing actions IAction TransitionInlet User action to leave a step.
Role Role IRole Role This is a group of users and groups. It can be associated to a set of common permissions or rights for an application, process, version, view.

Dynamic elements

When a document is creating, several elements are registered in the database. Among these elements we will keep the following:

  • IResource: interface representing the document data and from which it is possible to change the fields values;
  • IWorkflowInstance: interface branching off the interface IResource enabling to manage the document lifecycle (state change);
  • ILinkedResource: interface representing the data of a dynamic table row;
  • ITaskInstance: interface representing an active task on which some opertaors may intervene;
  • IResourceHistory: interface for accessing the document history;
  • IEvent: interface representing an event in the history;
  • IAttachment: interface enabling to handle attachment-type fields;
  • IOperator: interface representing a user operating on a step.

Diagram of dynamic elements classes

Dynamic element classes Dynamic element classes

Table of dynamic elements correspondence

Functional term Technical term SDK term EJB term (prefix:ejb/com/axemble/vdp/) Description
Resource Resource IResource Resource The term “Resource” represents the data container. It lets you store all the user data.
Request, Document Treatment IWorkflowInstance Treatment The notion of document has changed a lot in Process. It defines a resource and the set of associated treatments and sub-treatments.
Table line Internal resource ILinkedResource Resource This resource represents a resource of type dynamic table line.
Task to process Activity, manual activity ITaskInstance Activity, manual activity An activity represents an operation to be performed by a person or a program. A manual activity can be of two kind: Action or Decision.
History History IResourceHistory Document history.
History row User event IEvent Document history row corresponding to a user action.
Attachment, file File wrapper IAttachment Structure FileInfo or TempUploadFile Attached file description in the document via a attachment field.
Task to process User activity IOperator UsersActivity This is an association between a person and a manual activity. There should be as many users created as potential contributors determined for a task.
Linked requests, linked documents, sub-processes Linked treatment IWorkflowInstance Treatment This treatment represents a treatment type dynamic table line.

EJB API to SDK API

To move from API EJB to API SDK you just have to use the workflow module (IWorkflowModule). This object has a certain number of “getter” methods enabling to take as entries several natures of objects and to convert it in objects API SDK.

The definition objects

// recovering an application
public ICatalog getCatalog( Object object ) throws WorkflowModuleException;
// recovering a resource template
public IResourceDefinition getResourceDefinition( Object object ) throws WorkflowModuleException;
// recovering an property
public IProperty getProperty( Object object ) throws WorkflowModuleException;
// recovering a process
public IWorkflowContainer getWorkflowContainer( Object object ) throws WorkflowModuleException;
// recovering a process version
public IWorkflow getWorkflow( Object object ) throws WorkflowModuleException;
// recovering a task
public ITask getTask( Object object ) throws WorkflowModuleException;
// recovering an action
public IAction getAction( Object object ) throws WorkflowModuleException;
// recovering a role
public IRole getRole( Object object ) throws WorkflowModuleException;

The dynamic objects

// recovering a resource
public IResource getResource( Object object ) throws WorkflowModuleException;
// recovering a document
public IWorkflowInstance getWorkflowInstance( Object object ) throws WorkflowModuleException;
// recovering an active task
public ITaskInstance getTaskInstance( Object object ) throws WorkflowModuleException;
// recovering an element of an attachment field
public IAttachment getAttachment( Object object ) throws WorkflowModuleException;
// recovering a user of a user activity
public IOperator getOperator( Object object ) throws WorkflowModuleException;
// recovering a user
public IUser getUser( Object object ) throws WorkflowModuleException;

Example of recovering a IWorkflowInstance object from a Treatment object

public IWorkflowInstance system_getWorkflowInstance( IWorkflowModule module, Treatment treatment ) throws WorkflowModuleException {
	return module.getWorkflowInstance( treatment );
}

API SDK to API EJB

To move from the API SDK to the API EJB, you just have to use each one of the SDK objects and to call them on the method getNativeObject(). This one retrieves,based on the below table, the corresponding native object.

Example of recovering a Treatment object from a workflow instance

public Treatment system_getTreatment( IWorkflowInstance workflowInstance ) throws WorkflowModuleException {
	return ( (Treatment)workflowInstance.getNativeObject() );
}

General tasks with the Workflow module

Using the SDK API workflow module

The following code indicates how to use the workflow API. The method initialize() is used to position a certain number of parameters. In most of cases, this method will get the null value as argument, because inside the VDoc system every needed properties are positioned.

public void general_useModule() {
	// creation of an object of workflow module
	IWorkflowModule workflowModule = Modules.getWorkflowModule();
	
	try {
		// ...
		
	} catch( Exception e ) {
		// if an error has occurred
		getNavigator().processErrors( e );
	} finally {
		// do not forget to release the used module
		Modules.releaseModule(workflowModule);
	}
}

Recovering a context to use the SDK API

The context notion enables to run processing with a user account. Several cases are displayed. Their using depends on the execution context and the available objects.

public void general_getContext( IWorkflowModule workflowModule ) throws Exception {
	// 1st case : retrieving the context from a user object
	IUser user = workflowModule.getUserByLogin( "sysadmin" );
	IContext userContext = workflowModule.getContext( user );

	// 2nd case: retrieving the context from an external ID
	IContext extIDCtx = workflowModule.getContext( getNavigator().getLoggedOnUser().getExternId() );

	// 3rd case : retrieving the context from a login
	IContext loginContext = workflowModule.getContextByLogin( "sysadmin" );
}

Recovering an External Reference

This example shows how to recover the Java object corresponding to the external reference defined in the administration.

public void general_getExternalReference( IContext context, IWorkflowModule workflowModule ) throws Exception {
	// recovering an external reference with its name
	IJdbcReference jdbcReference = workflowModule.getJdbcReference( context, "vdocDatabase" );
	System.out.println( " référence : " + jdbcReference.getName() );
}

Recovering a DataSource

This example shows how to recover a DataSource defined on the JNDI server.

public void general_getDataSource( IWorkflowModule workflowModule ) throws Exception {
	IDataSourceReference dataSourceReference = workflowModule.getDataSourceReference( "education-ds" );
}

Recovering a connection from an external reference

From an external reference object, you may recover a JDBC connection.

public void general_getConnection( IJdbcReference jdbcReference ) {
	// recovering a connection
	Connection connection = jdbcReference.getConnection();
}

Recovering a connection from a DataSource

From a data source object, you may recover a JDBC connection.

public void general_getConnection( IDataSourceReference dataSourceReference ) {
	// recover a connection from a data source
	Connection connection = dataSourceReference.getConnection();
}

Using the transactions

In numerous cases, we need to gather several processing in a same transaction. Each module has its own transactional mechanism.

The following example shows how to use this transactional mechanism from the workflow module.

public void general_useTransaction( IContext context, IWorkflowModule workflowModule ) {
	try {
		// starting a transaction
		workflowModule.beginTransaction( this );

		// doing something
		// ...

		// validating the transaction
		workflowModule.commitTransaction( this );
		
	} catch( Exception e ) {
		// if an error has occurred, canceling the previous processing
		workflowModule.rollbackTransaction( this );
		getNavigator().processErrors( e );
	}
}