W4 EXTENSION BUS
TUTORIAL
Reference: EXTBUS_TUTORIAL_041_EN
W4 EXTENSION BUS
TUTORIAL
Reference: EXTBUS_TUTORIAL_041_EN
© 2008 - 2012 W4. All rights reserved.
The possession of this document gives you a non-transferable, non-exclusive and personal right to use it;
no proprietary rights are transferred to you. You may use, copy, reproduce and distribute this document
provided:
1. That the above notice of copyright is mentioned on all copies and that this notice appears
together with this authorisation,
2. That this document is used for informational purposes only and not for sale,
3. That this document is not modified in any way.
All product and brand names are the property of their respective owners.
The information in this document may be modified without prior notice.
Contents
Overview 6
Example 1 8
(Example 1) Developing the connector 8
(Example 1) Compiling the code 9
(Example 1) Creating and deploying the archive 9
(Example 1) Checking on the deployment 9
(Example 1) Preparing the connector description file 9
(Example 1) Testing the connector 11
Example 2 12
(Example 2) Developing the connector 12
(Example 2) Compiling the code 13
(Example 2) Creating and deploying the archive 13
(Example 2) Checking on the deployment 13
(Example 2) Final steps 14
W4 Extension Bus Tutorial
4
Example 3 16
(Example 3) Developing the connector
(Example 3) Compiling the code
16
17
(Example 3) Creating and deploying the archive
(Example 3) Checking on the deployment
(Example 3) Final steps
5
Contents
18
18
17
Chapter 1
1
Overview
This tutorial describes how to develop simple connectors intended to run with W4 Extension Bus:
 A connector whose function is to end a task
 A connector whose function is to return a list of variables and to modify a task variable
 A connector whose function is to return a list of task and workcase variables
This tutorial covers the various steps to developing the connectors:
Code creation
 Compilation
 Archive creation and deployment
 Creation of the XML description file for the connectors so that these are immediately available in
Process Composer
 Implementation of the connector in a Process Composer procedure model
 Connector operating test via the generation of an application in Process Composer

This chapter introduces the connectors you will be developing with the tutorial, and sets outs the
prerequisites that you should respect prior to start any connector development.
Software configuration
You should have the following software installed on your development station:
 Process Engine, version 6.5 or later
 W4 Extension Bus, version 6.5 or later
 Process Composer, version 6.5 or later
 A JDK (Java Development Kit), version 1.5 or later
W4 Extension Bus Tutorial
6
Setting the environment variables
Make sure the PATH environment variable correctly points to the JAVA_HOME environment variable
and that the latter correctly references the JDK in use.
Work environment
We recommend that you use a work environment with the following directories:
 src: Target directory for the source files (extension in .java)
 lib: Files required to compile the connectors. To this directory you should copy the
W4 Extension Bus library - extbus.jar - which can be found in:
<W4ExtensionBus_Home>\product\common\lib


build: Target directory for the compiled files (extension in .class)
dist: Target directory for the archive files (extension in .jar)
Useful resources
Consult the Javadoc for W4 Extension Bus, available in the W4 Extension Bus documentation.
Consult the Javadoc for W4 BPM API, available in the Process Engine documentation.
7
Chapter 1 Overview
Chapter 2
2
Example 1
This tutorial describes how to develop a simple connector intended to run with W4 Extension Bus
and whose function is to end a task.
2.1
(Example 1) Developing the connector
Any connectors intended to run with W4 Extension Bus must inherit from the W4Connector class.
The W4Connector class is located in the eu.w4.connector package.
The service() method is obligatory to implement the W4Connector class. This class specifies the
behaviour of the connector via the W4Result object and its enumeration W4ResultAction.
This example describes how to develop a very simple connector as it will content itself with
implementing the service() method to end a task. To perform this operation, it will need to
implement the SUBMIT enumeration of the W4Result object.
NOTE
Consult the Javadoc for W4 Extension Bus, available in the W4 Extension
Bus documentation.
The code for this connector is as follows:
// Importing the W4 Extension Bus package
import eu.w4.connector.*;
// Specifying the connector name and version
@W4aConnectorDescription(name="SubmitConnector", version="1.0")
public class SubmitConnector extends W4Connector
{
// Implementing the mandatory service() method
public W4Result service() throws W4ConnectorExecutionException
{
W4Result result = new W4Result(W4ResultAction.SUBMIT);
return result;
}
W4 Extension Bus Tutorial
8
}
Save this code to a file named SubmitConnector.java inside your src directory.
2.2
(Example 1) Compiling the code
Run the following command to compile the connector (change as required to fit your directory
names):
javac -classpath lib\extbus.jar -sourcepath src -d build src\*.java
2.3
(Example 1) Creating and deploying the archive
Run the following command to create the archive for the connector (change as required to fit your
directory and file names) :
jar -cf dist\SubmitConnector.jar -C build SubmitConnector.class
Copy the SubmitConnector.jar archive to the following directory:
<W4ExtensionBus_Home>\product\connectors\simple\connector
Restart Process Engine.
2.4
(Example 1) Checking on the deployment
Consult the extbus<i>.log log file located in <W4Engine_Home>\adm\log\<instanceName>.
A notification such as Successfully loaded connector should be logged:
Febr 26 2008 17:32:23 eu.w4.connector.W4CnnLoader loadConnectors
INFO: Successfully loaded connector 'SubmitConnector', version
'1.0'.
2.5
(Example 1) Preparing the connector description file
So that they can be used in procedure models, any connectors should be made available in Process
Composer. This is achieved via a descriptive file in XML format.
9
Chapter 2 Example 1
This file should be named after the connector and should be placed in:
<ProcessComposer_Home>\lib\connector.
For further details regarding this file, please refer to the Process Composer Modelling guide.
Sample file
<?xml version="1.0" encoding="UTF-8"?>
<CONNECTOR xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="Connector.xsd"
version="1.0"
VersionModel="1.0">
<NAME id="SubmitConnector">
<LABEL lang="fr">Exemple simple</LABEL>
<LABEL lang="en">Simple sample</LABEL>
</NAME>
<CATEGORY>
<LABEL lang="fr">Exemples</LABEL>
<LABEL lang="en">Samples</LABEL>
</CATEGORY>
<DESCRIPTION>
<LABEL lang="fr">Exemple de connecteur simple</LABEL>
<LABEL lang="en">Simple connector sample</LABEL>
</DESCRIPTION>
<ICON path="lib\connector\Images\Submit.gif"/>
<VARIABLES>
</VARIABLES>
<PROPERTIES>
</PROPERTIES>
</CONNECTOR>
IMPORTANT
The id attribute of the NAME mark-up should correspond with
the value of the NAME attribute of the W4aConnectorDescription annotation.
If the W4aConnectorDescription annotation has not been implemented, the id
attribute of the NAME mark-up should correspond with the class name for the
connector.
Process Composer makes use of the information provided by the connector description file, which
makes it easy to use the connector in procedure models:
 In the property window for the corresponding robot node, after you have selected Connector
step in the Specific type field, you can select the connector in the Connector name field.
 If properties were specified in the PROPERTIES section, these are displayed in the Extended
attributes folder of the property window.
 If an icon was specified in the ICON item, this substitutes the graphical representation for the
node in the modelling window when the connector is selected in the Connector name field.
 The activity for the connector step is automatically created in the Activities folder, in the work
area explorer.
 The variables that have been specified in the VARIABLES section are automatically created in the
Activity variables window and the Variable mapping window is pre-filled in the In, Connector
variables and Out columns.
NOTE
If Process Composer does not provide this information, use the command:
EditLoad connectors
W4 Extension Bus Tutorial
10
2.6
(Example 1) Testing the connector
In Process Composer, create a test procedure with a robot step node. In the property window for that
node, select Connector step in the Specific type field. You should then be able to select your
connector in in the Connector name field.
Verify the procedure then send it to the Process Engine server.
So that the procedure is valid, you should have:
 Specified the responsible role for the procedure (Role > Responsible role field in the procedure
property window)
 Created (in the Activities folder of the work area explorer) and assigned (Activity field in the node
property window) an activity to every node step
 Specified the assignment mode for every step node (Assignment folder in the node property
window)
Send the procedure to the Process Engine server.
When the procedure is being sent, Process Engine automatically creates an actor with the name of
the connector (corresponding with the id attribute of the NAME item in the connector description
file), to whom the tasks related to the connector will be assigned. So that such tasks are correctly
assigned to this actor, you must assign the extensionconnector role to him.
Generate an application based on the procedure then deploy it in Tomcat.
11
Chapter 2 Example 1
Chapter 3
3
Example 2
This tutorial describes how to develop a simple connector intended to run with W4 Extension Bus
and whose function is to return a list of variables and to modify a task variable.
3.1
(Example 2) Developing the connector
This example describes how to develop a simple connector whose function is to return a list of
variables and to modify a task variable.
NOTE
Consult the Javadoc for W4 Extension Bus, available in the W4 Extension
Bus documentation, and also the Javadoc for W4 BPM API, available in the
Process Engine documentation.
The code for this connector is as follows:
import eu.w4.connector.*;
import eu.w4.bpm.*;
import eu.w4.bpm.service.*;
@W4aConnectorDescription(name="ChangeTaskVarConnector")
public class ChangeTaskVarConnector extends W4Connector
{
@Override
public W4Result service() throws W4ConnectorExecutionException
{
BPMVariableMap outVarMap = BPMVariables.createVariableMap();
try
{
BPMVariableMap
inVarMap
=
getBPMTaskSnapshot().getAttachedTaskVariables();
String
inVarValue
=
inVarMap.get("Var_StringTest").getValue() + "_MOD";
BPMVariable
outVar
=
BPMVariables.createVariable("Var_StringTest",
BPMDataType.STRING,
W4 Extension Bus Tutorial
12
inVarValue);
outVarMap.put(outVar);
}
catch(BPMIncompleteSnapshotException e)
{
getLogger().error(e);
}
return new W4Result(W4ResultAction.SUBMIT, outVarMap, null);
}
}
Save this code to a file named ChangeTaskVarConnector.java inside your src directory.
3.2
(Example 2) Compiling the code
Run the following command to compile the connector (change as required to fit your directory
names):
[UNIX] javac -classpath lib/extbus.jar:lib/w4bpmapi.jar -sourcepath src -d
build src/*.java
[Windows] javac -classpath lib\extbus.jar;lib\w4bpmapi.jar -sourcepath src -d
build src\*.java
3.3
(Example 2) Creating and deploying the archive
Run the following command to create the archive for the connector (change as required to fit your
directory and file names):
jar -cf dist\ChangeTaskVarConnector.jar -C build
ChangeTaskVarConnector.class
Copy the ChangeTaskVarConnector.jar archive to the following directory:
<W4ExtensionBus_Home>\product\connectors\simple\connector
Restart Process Engine.
3.4
(Example 2) Checking on the deployment
Consult the extbus<i>.log log file located in <W4Engine_Home>\adm\log\<instanceName>. A
notification such as Successfully loaded connector should be logged:
Febr 26 2008 17:32:23 eu.w4.connector.W4CnnLoader loadConnectors
13
Chapter 3 Example 2
INFO: Successfully
version '1.0'.
3.5
loaded
connector
'ChangeTaskVarConnector',
(Example 2) Final steps
Preparing the connector description file
Please refer to the following section:
> 2.5 (Example 1) Preparing the connector description file, page 9
Testing the connector
Please refer to the following section:
> 2.6 (Example 1) Testing the connector, page 11
W4 Extension Bus Tutorial
14
15
Chapter 3 Example 2
Chapter 4
4
Example 3
This tutorial describes how to develop a simple connector intended to run with W4 Extension Bus
and whose function is to return a list of task and workcase variables.
4.1
(Example 3) Developing the connector
This example describes how to develop a simple connector whose function is to return a list of task
and workcase variables.
NOTE
Consult the Javadoc for W4 Extension Bus, available in the W4 Extension
Bus documentation, and also the Javadoc for W4 BPM API, available in the
Process Engine documentation.
The code for this connector is as follows:
import
import
import
import
eu.w4.connector.*;
eu.w4.bpm.*;
eu.w4.bpm.service.*;
eu.w4.bpm.search.*;
@W4aConnectorDescription(name="GetTaskCaseVarConnector")
public class GetTaskCaseVarConnector extends W4Connector
{
@Override
public W4Result service() throws W4ConnectorExecutionException
{
BPMVariableMap outVarMap = BPMVariables.createVariableMap();
try
{
BPMVariableMap inVarMap =
getBPMTaskSnapshot().getAttachedWorkcaseVariables();
int
inVarValue
=
(Integer)(inVarMap.get("anIntVariable").getValue()) + 1;
BPMVariable
outVar
=
W4 Extension Bus Tutorial
16
BPMVariables.createVariable("Var_StringTest",
BPMDataType.STRING,
"" + inVarValue);
outVarMap.put(outVar);
}
catch(BPMIncompleteSnapshotException e)
{
getLogger().error(e);
}
return new W4Result(W4ResultAction.SUBMIT, outVarMap, null);
}
// Overriding this method requires W4 Extension Bus to supply
also the workcase variables
@Override
public
BPMTaskAttachment
getBPMTaskAttachment()
throws
BPMException
{
BPMTaskAttachment l_bpmTaskAttachment =
getBPMService().getTaskService().createTaskAttachment();
l_bpmTaskAttachment.attachAllTaskVariables();
l_bpmTaskAttachment.attachAllWorkcaseVariables();
return l_bpmTaskAttachment;
}
}
Save this code to a file named GetTaskCaseVarConnector.java inside your src directory.
4.2
(Example 3) Compiling the code
Run the following command to compile the connector (change as required to fit your directory
names):
[UNIX] javac -classpath lib/extbus.jar:lib/w4bpmapi.jar -sourcepath src -d
build src/*.java
[Windows] javac -classpath lib\extbus.jar;lib\w4bpmapi.jar -sourcepath src -d
build src\*.java
4.3
(Example 3) Creating and deploying the archive
Run the following command to create the archive for the connector (change as required to fit your
directory and file names):
jar -cf dist\GetTaskCaseVarConnector.jar -C build
ChangeCaseVarConnector.class
Copy the GetTaskCaseVarConnector.jar archive to the following directory:
<W4ExtensionBus_Home>\product\connectors\simple\connector
Restart Process Engine.
17
Chapter 4 Example 3
4.4
(Example 3) Checking on the deployment
Consult the extbus<i>.log log file located in <W4Engine_Home>\adm\log\<instanceName>. A
notification such as Successfully loaded connector should be logged:
Febr 26 2008 17:32:23 eu.w4.connector.W4CnnLoader loadConnectors
INFO: Successfully loaded connector 'GetTaskCaseVarConnector',
version '1.0'.
4.5
(Example 3) Final steps
Preparing the connector description file
Please refer to the following section:
> 2.5 (Example 1) Preparing the connector description file, page 9
Testing the connector
Please refer to the following section:
> 2.6 (Example 1) Testing the connector, page 11
W4 Extension Bus Tutorial
18
19
Chapter 4 Example 3
Illustrations
W4 Extension Bus Tutorial
20
21
Illustrations
Index
A
Archive, create 9
Archive, deploy 9
C
Connector description file 9
E
Environment variables 7
eu.w4.connector package 8
J
Java Development Kit 6
JAVA_HOME environment variable 7
JDK
6, 7
P
PATH environment variable 7
Process Composer 6, 9, 10, 11
Process Engine 6
S
service() method 8
W4 Extension Bus Tutorial
22
Software configuration 6
T
Tests
11
W
W4 Extension Bus 6
W4Connector class 8
W4Result object 8
Work environment 7
23
Index
W4 EXTENSION BUS
TUTORIAL
Reference: EXTBUS_TUTORIAL_041_EN