The Danet Workflow Component

The specified workflow APIs (packages de.danet.an.workflow.omgcore and de.danet.an.workflow.api, see Section 3.2, “Client API”) are packaged in a separate jar de.danet.an.wfcore-apis.jar located in the distribution directory $DIST/lib/wfcore. Only this JAR file should be used in the classpath when compiling clients. Consequently, it must also be included in the runtime classpath of a client.

The runtime-classes needed by a client that wants to use the workflow component are provided as de.danet.an.wfcore-client.jar in $DIST/lib/wfcore. This JAR file is not self contained, i.e. it relies on the presence of the workflow APIs (de.danet.an.wfcore-apis.jar), the Danet AN utility classes (de.danet.an.util.jar, see following section) and the additional libraries described in Section 1.3.7, “Additional libraries”. In addition, the client needs some information about how to contact the server. See the description of the basic WorkflowServiceFactory (in Section A.2.52, “Class WorkflowServiceFactory”), the description of the WfMOpen specific factory implementation (in de.danet.an.workflow.ejbs.client.StandardWorkflowServiceFactory) and the remarks in Section 1.3.4, “Workflow module” below.

All J2EE based software from the division AN uses a library with some common utility objects and components. This library is supplied as de.danet.an.util.jar (again located in the $DIST/lib/wfcore). Some components in this library (currently the logging service) need server side support. This support is provided by the corresponding EJB module described below.

The Danet AN utility library (package de.danet.an.util) is a general library used at our site. This library is packaged as two JAR files. By default, classes are in de.danet.an.util.jar. Some classes in the package (sub-package de.danet.an.util.jsf), however, are helper classes for JSF based portlets. These classes are are not included in de.danet.an.util.jar. They can be found in de.danet.an.util-jsf.jar. The reason for separating those classes is that they may not be put in the common classpath of a J2EE application. In order to avoid classpath problems, you have to put these JSF utility classes in the same directory as the JSF libraries (usually the WEB-INF/lib directory of your web module). Note that the classes from de.danet.an.util.jsf are only needed by the portlets that come with the workflow component. The deployment of the workflow EJBs requires de.danet.an.util.jar only.

The central (server side) workflow component is an EJB-type J2EE module. This module is not self contained, i.e. it relies on the presence of the workflow APIs, the Danet AN utility library and the additional libraries listed below. The module is located in the distribution directory $DIST/lib/wfcore as de.danet.an.wfcore-ejbs.jar.

The manifest file of de.danet.an.wfcore-ejbs.jar includes in its Class-Path: statement the entries lib/de.danet.an.wfcore-apis.jar and lib/de.danet.an.util.jar. Thus, the dependencies between the workflow module, the workflow APIs and the Danet AN utility library will be resolved automatically if de.danet.an.util.jar is put in the lib/ directory of the enterprise archive (the .ear-file). An additional Class-Path: entry lib/de.danet.an.wfcore-plugins.jar serves as a hook for adding jars with tool agents (see Section 3.5, “Tool invocation SPI”) to the class path. We recommend to put new tool agents or other libraries that are to be deployed with the engine core in extra add-on jar files. Then create a jar de.danet.an.wfcore-plugins.jar with only a META-INF/MANIFEST.MF that references your jars in its Class-Path: entry and add this (along with your add-on jars) to the EAR as lib/de.danet.an.wfcore-plugins.jar. The application server will then load de.danet.an.wfcore-plugins.jar (because it is referenced in de.danet.an.wfcore-ejbs.jar) and subsequently your jars with additional components.

The actual work during process execution is done by tool agents (see Section 3.5, “Tool invocation SPI”). Several of these tool agents are included in WfMOpen (see Chapter 5, Tools). Usually projects will add their own specific tool agents. In simple deployment scenarios, this can easily be done by adding jars with tool agent implementations as described above in Section 1.3.4, “Workflow module”.

In more complex deployment scenarios, there is a drawback to this approach. Consider an application with a core EAR that contains, among other components, WfMOpen. Other EARs provide additional services. In order to invoke these services from the workflow engine with specific tool agents, the agents would have to be bundled with the core EAR. But this would create a dependency on services and classes in the additional EAR and thus effectively a circular dependency. It would also be hard to have a consistent application server startup. If the engine is deployed first it may try to invoke a tool agent that requires services from an EAR that is not completely deployed yet.

In order to support such deployment scenarios, WfMOpen provides the callback module de.danet.an.wfcore-callback-ejbs.jar that may be bundled with the additional service EARs and executes tool agent invocations in the context of these service EARs. The callback module bundles two EJBs that are also contained in the core workflow module: an EJB that reads messages from the application invocation queue and an EJB (the InvocationHelperEJB) that invokes the tool agents. Tool agent invocations are forwarded to callback EJBs by specifying a Handler attribute for the application declaration in the process definition (see Section 4.2.5.1, “Extentions of Application Declaration”). Configuring the callback module is described in Section 1.4.4, “Callback module deployment”.

As described above, all J2EE based software from the division AN uses some common utility objects and components. While most of these elements can be simply supplied as a library, some components (currently the logging support) consist of a client and a server part. The J2EE server side elements are packaged in the distinct EJB-type J2EE module de.danet.an.util-ejbs.jar that is also located in the $DIST/lib/wfcore distribution directory. This module must be deployed along with the workflow module.

As the utility module is intended to be used in several applications, we have deliberately not defined defaults for some information needed during deployment. Providing defaults for these values would imply the risk that different applications inadvertently access each others utility EJBs. Instead of defaults we use symbolic names in the deployment descriptors that can reliably be replaced automatically.

All symbolic names are described below. The description should be sufficient to allow you to adapt the deployment descriptors for your application. For more information about these EJBs, see the maintenance manual.

The symbolic names used are:

As distributed, the utility module's descriptors do not specify any security constraints. We do, however, strongly recommend adding such constraints as appropriate for an application's security domain when assembling the application^[6]. A common configuration is to introduce the same security role as used for the workflow engine EJBs (i.e. "WfMOpenAdmin", see Section 1.3.4, “Workflow module”) and allow this role to execute all methods.

The module includes support for executing the required adaptions. See Section 1.4.1, “Preparing the modules” for details.

As is usually the case with complex Java applications, the workflow component needs some third party libraries in addition to the standard JDK. Those libraries are:

When you want to use WfMOpen with JDK/JRE 1.4, updated versions of the JRE XML packages (org.w3c.dom, org.xml.sax, org.xml.sax.ext and org.xml.sax.helpers) are needed. You you must therefore use the Endorsed Standards Override Mechanism of the JDK to provide those newer versions, i.e. you have to set the system property java.endorsed.dirs to the directory $DIST/lib/wfdemo/endorsed^[7]. For the versions of the XML libraries currently used see the CVS information in the tools/endorsed subdirectory.

As has been described in the previous sections, the deployment descriptors of the EJB modules must be adapted to the application that integrates the workflow engine. In order to facilitate this task, the EJB JARs have in their subdirectory assembly-resources ant scripts with targets that may be called to perform the adaption. Of course, these scripts do not have to be used to adapt the EJBs, they are simply provided as useful helpers.

# # Information needed for
        application assembly #

# Adapt utility EJBs' JNDI names. They have no "reasonable" defaults,
# so we have to specify very much. Note that these JNDI names are
# define separately as the utility EJBs may be shared between
# different applications. Note that "ejb/" will be prepended to the names
# specified below automatically and the entries for local home interfaces
# have "Local" appended to the name.
@@@_Utility-EJBs_UtilEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.Util
@@@_Utility-EJBs_KeyGenEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.KeyGen
@@@_Utility-EJBs_KeyGenLockEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.KeyGenLock
@@@_Utility-EJBs_EJBSinkEJB_JNDI_Name_@@@ = \
          de.danet.an.wfdemo.util-lib.EJBSink
# Adapt utility EJB's data source reference
java\:/DefaultDS = java:/WfMOpenDS

# Adapt other EJBs' JNDI names. Most application servers require that
# you specify JNDI names although all references to the EJB are via
# links within the application. We simply define a prefix for those.
# This prefix is also used for JNDI names of other resources. Note that
# "ejb/" will be prepended to the prefix specified below when used to
# derive JNDI names for EJBs.
@@@_JNDI_Name_Prefix_@@@ = de.danet.an.wfdemo.

util-ejbs-security-domain = java:/jaas/wfdemo
util-ejbs-security-roles = \
  WfMOpenAdmin: \
    KeyGen*KeyGenLock*EJBSink*Util;
util-ejbs-security-identities = TimeoutHandler:WfMOpenAdmin
util-ejbs-security-principals = TimeoutHandler:WfMOpenAdmin_Principal

# Adapt workflow engine (note that the engine uses the util EJBs, 
# necessary replacements are already covered by the properties above).
java\:/jaas/wfmopen = java:/jaas/wfdemo

The workflow EJBs can be deployed in the usual way defined by J2EE:

<application>
  <display-name>My application using WfMOpen</display-name>
  <module>
    <ejb>de.danet.an.util-ejbs.jar</ejb>
  </module>
  <module>
    <ejb>de.danet.an.wfcore-ejbs.jar</ejb>
  </module>

  <module>
    <ejb>some.user.my.application.jar</ejb>
  </module>
</application>

Make sure that you have included all libraries needed by the workflow EJBs in the lib/ directory of your J2EE application as described in Section 1.3.4, “Workflow module”. This is a usable configuration if you only define workflow processes without any resources (i.e. only automatically executed activities). If resource assignment to activities is needed, some additional services have to be supplied as described below.

If you combine the workflow engine EJBs and servlets (packed as WARs) in a single EAR, it is advisable to have libraries used by both components only in the EAR (i.e. not in the WARs' WEB-INF/lib directory. In such a configuration, the libraries must explicitly be deployed as Java modules in application.xml. Note that this and other packaging aspects are not WfMOpen specific. Rather they apply to J2EE applications in general and details are bexond the scope of this manual. See one of the many books about J2EE for further informations.

An issue not necessarily handled by a workflow core service is the issue of resource assignment. The OMG specification explicitly leaves this topic to a to-be-defined resource assignment facility. We have therefore chosen to introduce a simple interface to a resource assignment service in our design. This interface is described in detail in the package de.danet.an.workflow.spis.ras.

In order to keep this interface easily implementable by any kind of architecture, access to this service is not based on JNDI and an EJB home interface. Access rather follows the established generic pattern to create a service using a factory class. In order to use the workflow component, an implementation of this service must be provided.

The workflow component includes a sample implementation of a resource assignment service. If you want to use this implementation, some additional configuration issues arise which are discussed in Section 6.1, “The sample assignment service”.

The callback module should be adapted by using the target "prepare-wfmopen-callback-module" as described in Section 1.4.1.2, “Helpers for adapting the workflow engine EJBs”. This requires basically the same properties as adapting the core modules, i.e. a basic knowledge about the workflow engine configuration. In order to distinguish the callback EJBs from the ones used in the engine core and in other callback module configurations, each deployment must specify an individual additional property @@@_JNDI_Callback_Name_Prefix_@@@. This is used to derive the global JNDI name of the callback EJBs. To avoid a complete properties file for every callback module adaption, this property may be put in its own properties file. This properties file is then passed to the invocation of the ant target as property token-replacements. "Token-replacements" is a mechanism supported by the ant helpers that allows to override (and therefore also add) individual properties in the general properties file.

Also required is the specification which tool agent invocations are to be handled by the callback module. This is determined by the ant property handler. Its value must correspond with the value of the attribute Handler used for the application declaration in the process definition (see Section 4.2.5, “Defined extensions”).

Debugging mode is enabled for a specific process by calling setDebugEnabled(true) on the process after creating, but before starting the process (see setDebugEnabled(boolean)).

Debugging can also be enabled for a process type by default using the XPDL extension mechanism as described in Section 4.2.5.2, “Extensions on Package and Process Level”.

When debug mode is enabled, the execution of activities breaks before the invocation of a tool and before completion of an activity.

Immediately before invoking a tool, the activity's state changes to open.running.debug.invoking. To continue the execution, the activity's state must be changed to either open.running or to open.running.debug.skipping. In the former case, the tool will be invoked as in non-debugging mode. In the latter case, tool invocation will be skipped and the activity will either assume the state open.running.debug.invoking again (if there are more tools to be executed by the activity) or the state open.running.debug.completing (if the invocation of the last tools has been skipped, see below). Of course, the process data must subsequently be modified manually to reflect the changes that would have been made by the tool invocation.

Before the activity is eventually closed, it enters one of the states open.running.debug.terminating, ...aborting or ...completing depending on the closed-state that the activity will assume. To continue execution and cause the activity to assume it proper closed state, the activity's state must be changed to open.running.

In debugging mode, exceptions thrown by tools (i.e. calls to abandon, see abandon(java.lang.String) will cause the activity to assume the state open.running.debug.abandoning. To continue the execution, it is not sufficient to provide the possibility to change the state to open.running as described above for the "normal" transitions to the closed state. There may be several exceptional transitions defined, and it must be possible to specify which exception should be used, else it wouldn't be possible to test the different paths during debugging.

In order to avoid polluting the interface with methods that are only used for debugging, we have defined a special sequence of method invocations that cause the execution to continue (i.e. the state will change to closed.completed.abandoned and the execution of subsequent activities will be triggered as specified by the transitions). You first change the state to open.running.debug.awaiting_exception and then call abandon (see abandon(java.lang.String)) with the name of the exception to be processed. The preceding state change causes abandon(String) to behave differently from normal operation, effectively continuing execution as described above.

In order to avoid any ambiguities, we strongly recommend to execute the two operations (state change and abandoning) in a single transaction. This may be achieved by using a user transaction as described in the J2EE specification or by using the method invocation batch (see Section A.2.31, “Class MethodInvocationBatch”).

WorkflowService wfs = ...;
MethodInvocationBatch mib = new MethodInvocationBatch(true);
mib.addInvocation (activity, "changeState", 
		   new String[] {"java.lang.String"},
		   new Object[] {"open.running.debug.awaiting_exception"});
mib.addInvocation (activity, "abandon",
		   new String[] {"java.lang.String"},
		   new Object[] {exception});
MethodInvocationBatch.Result mir
    = (MethodInvocationBatch.Result)wfs.executeBatch(mib);

Deadlines will be be started in debugging mode just as in non-debugging mode. However, nothing happens when deadlines are reached. The state of deadlines may be monitored by calling deadlines(). To cause the process to proceed as if a synchronous deadline had been reached, you must first call abandon(String), which causes the activity to assume the state open.running.debug.abandoning, and then continue execution as described for exceptions in general above (see Section 2.6.3, “Effect on exceptions”). This may, of course, be done before the deadline has been reached, i.e. the effect of a deadline may be tested without actually waiting for the associated time (which may be quite long) to elapse.

In order to simulate an asynchronous deadline, the state of an activity must first be changed to open.running.debug.forwarding_exception. This causes a subsequent call to abandon to mimic the behavior of an asynchronous deadline, i.e. transitions will be triggered as specified for the given exception. The activity will automatically resume the state that it had before the change to open.running.debug.forwarding_exception. Of course, this sequence of method calls should also be executed in a single transaction, as described above.

As a first step, we have adapted the API specified by OMG's Workflow Management Facility Specification, V1.2 to the Java domain. The result of this adaptation can be found in the package description of de.danet.an.workflow.omgcore (see de.danet.an.workflow.omgcore or JavaDoc). The package defines the core workflow classes such as WfProcess, WfActivity etc. A detailed description of the process used to derive the Java interfaces from the OMG specification can be found in the package description.

The OMG core workflow interfaces define a workflow model as shown in the following diagram.

Figure 3.2. OMG core workflow model

The central classes of the model are WfProcess (see Section A.1.42, “Interface WfProcess”) and its constituting WfActivity instances (see Section A.1.29, “Interface WfActivity”). Processes of the same type can be created and accessed with their WfProcessMgr (see Section A.1.43, “Interface WfProcessMgr”).

Examining the OMG interface closely, we found that it lacks some functions that we would like to offer. For some OMG interfaces we have in a second step therefore defined a corresponding interface that extends the OMG base interface.

We have also added some interfaces for areas that the OMG specification has purposely omitted from its scope (e.g. access to process definitions).

The starting point for using the workflow engine is the WorkflowServiceFactory. Use this class to create a new WorkflowService (see Section A.2.52, “Class WorkflowServiceFactory”, especially setProperty(java.lang.String, java.lang.Object), and Section A.2.51, “Interface WorkflowService”). The workflow service provides the methods to access the process definitions, processes etc.

Note that the extended API has been defined completely independent of J2EE. It is possible to implement this API with POJOs, though it may turn out to be difficult to provide remote access, reliable transactional behavior, security and scalability without using J2EE.

The implementation of the API provided by WfMOpen is J2EE based because we found this middleware an ideal basis for a workflow engine that can meet the demands of enterprises. The workflow service factory implementation provided by WfMOpen is described in de.danet.an.workflow.ejbs.client.StandardWorkflowServiceFactory. See this description for more information about required configuration parameters.

Let's start with a first look at the code we need for this purpose:

package samples;

import java.util.Iterator;
import java.rmi.RemoteException;

import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;

import de.danet.an.workflow.api.WorkflowServiceFactory; 
    // Section A.2.52, “Class WorkflowServiceFactory”
import de.danet.an.workflow.api.WorkflowService; 
    // Section A.2.51, “Interface WorkflowService”
import de.danet.an.workflow.api.ProcessDirectory; 
    // Section A.2.44, “Interface ProcessDirectory”
import de.danet.an.workflow.omgcore.WfProcess; 
    // Section A.1.42, “Interface WfProcess”

import ProjectLoginContext; // Section 3.3.2, “Gaining access”

/**
 * A sample workflow client.
 */
public class TestClient {

    private static LoginContext lctx = null; 

    /**
     * Main method called when started from shell.
     * @param args arguments
     */
    public static void main(String args[]) {
	System.out.println("Started");

        // This block authenticates a user. It is needed only once
        // within a client program (see Section 3.3.2, “Gaining access”).
	try { // ❶
	    lctx = new ProjectLoginContext();
	    lctx.login();
	} catch (LoginException exc) {
	    System.err.println("Login failed: " + exc.getMessage());
	    System.exit(-1);
	}

        // Here starts the real work.
	WorkflowService wfs // ❷
            = WorkflowServiceFactory.newInstance().newWorkflowService();
	try {
	    ProcessDirectory dir = wfs.processDirectory(); // ❸
	    Iterator procs = dir.processes().iterator();  // ❹
	    while (procs.hasNext()) {
		System.out.println
                    ("Proc: " + ((WfProcess)procs.next()).name()); // ❺
	    }
	} catch(RemoteException exc) {
	    System.err.println
                ("Process directory not accessible: " + exc.getMessage());
	    System.exit(-1);
	}
    }
}

Preparations

First of all, you have to install the database (see Section 1.2, “Preparing the database”) and deploy the workflow ejbs (see Section 1.4, “Deploying the component”).

If you have installed a demo application (see Appendix C, The demo applications) you can use it as the server for the sample client.

Building environment

Next, add the following libraries to your compilation classpath:

You should now be able to compile the sample client code.

Running the client

After the successful compilation of your client, you need to add the following items to your runtime classpath:

If you now try to start the sample client, you will get an error message, stating that the environment is unable to locate a login configuration. This is due to the fact that every access to an EJB is security controlled by the application container.

Gaining access

Access to EJBs may be secured by specifying roles that have access to methods. In the sample application, a single security role named WfMOpenAdmin has been configured, which a user has to adopt in order to gain full access to all application components (see the ejb-jar.xml in the de.danet.an.wfcore-ejbs.jar).

Since the J2EE specification does not define how to associate roles with a client, things get a bit vendor-specific here. Lookup your J2EE server's documentation to find out how things are handled in your environment. A popular method used by several J2EE vendors is to use JAAS based authentication. We'll explain the mechanism using the JBoss application server as an example.

Roughly, JAAS is based on a session related LoginContext that holds security information (including associated roles) about a Principal (typically a user's login name). One or more configurable "login modules" provide this information. The login modules are invoked when LoginContext.login() is called (see ❶). The login modules may use a callback to query credentials. If proper credentials are supplied, the login module adds information (such as roles) to the LoginContext.

If you have no predefined callback implementations available, you may use this example:

import java.io.IOException;

import javax.security.auth.Subject;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.UnsupportedCallbackException;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.TextOutputCallback;
import javax.security.auth.callback.NameCallback;
import javax.security.auth.callback.PasswordCallback;
import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;
import javax.security.auth.login.FailedLoginException;

/**
 * Simple login context for unit tests.
 */
public class ProjectLoginContext extends LoginContext {

    public final static String USERNAME = "junit";

    private static class CBH implements CallbackHandler {
	public void handle (Callback[] callbacks) ❶
	    throws UnsupportedCallbackException, IOException {
	    for (int i = 0; i < callbacks.length; i++) {
		if (callbacks[i] instanceof TextOutputCallback) { ❷
		    // display the message according to the specified type
		    TextOutputCallback toc = (TextOutputCallback)callbacks[i];
		    switch (toc.getMessageType()) {
		    case TextOutputCallback.INFORMATION:
			System.err.println(toc.getMessage());
			break;
		    case TextOutputCallback.ERROR:
			System.err.println("ERROR: " + toc.getMessage());
			break;
		    case TextOutputCallback.WARNING:
			System.err.println("WARNING: " + toc.getMessage());
			break;
		    default:
			throw new IOException("Unsupported message type: " +
					      toc.getMessageType());
		    }
		} else if (callbacks[i] instanceof NameCallback) { ❸
		    // prompt the user for a username
		    NameCallback nc = (NameCallback)callbacks[i]; 
		    nc.setName(USERNAME);
		} else if (callbacks[i] instanceof PasswordCallback) { ❹
		    // prompt the user for sensitive information
		    PasswordCallback pc = (PasswordCallback)callbacks[i]; 
		    pc.setPassword(USERNAME.toCharArray());
		} else {
		    throw new UnsupportedCallbackException
			(callbacks[i], "Unrecognized Callback");
		}
	    }
	}
    }

    public ProjectLoginContext () throws LoginException {
	super ("danetworkflow", new CBH()); ❺
    }
}

The security configuration name used by the LoginContext must match an entry in the file that declares all security domains for JAAS. For our client (and JBoss) we need an entry like this:

danetworkflow {
    org.jboss.security.ClientLoginModule required;
}; 

This declares that a single login module org.jboss.security.ClientLoginModule should be called.

Finally we must tell JAAS that it should use our configuration file by starting the java virtual machine with this additional parameter: -Djava.security.auth.login.config=auth.conf.

The login context in our example provides credentials for the user “junit”. So we have to make sure, that the user “junit” is able to adopt the role StaffManagementRole_0. The described JBoss security configuration verifies given credentials on the basis of the Jetspeed2 user management component. Thus, to gain the proper access rights, make sure that a user name “junit” is defined within the Jetspeed2 portal and that this user is part of the administrator group (the group with the id “0”).

With these security settings, the client should now display a list with all processes currently running (or closed but not deleted) in the workflow engine.

As explained in the package description of the application invocation interface (see de.danet.an.workflow.spis.aii), tool agent invocations are conceptually asynchronous, i.e. the workflow engine does not expect the invoke method to return a value. This is a necessity for supporting tools that run for a long period of time (e.g. a tool that allows manual input of data). The process that calls complete on the activity may be completely different from the thread that invoked the tool agent.

Practical experience shows, however, that a lot of tools can reasonably execute completely within the invoke method. In order to simplify the implementation of this class of tools and avoid some problems with transactions (again, see de.danet.an.workflow.spis.aii for details), the interface ResultProvider (see Section A.3.8, “Interface ResultProvider”) has been defined. A tool agent implementing this interface can provide its result in a simple function call and the workflow engine handles forwarding the result to the activity and completing the activity.

Sometimes, tool agents need access to some workflow engine functions. While it is technically possible for tool agents to access the WorkflowEngineEJB (and older versions of the tools coming with WfMOpen did rely on this), this behavior is strongly discouraged. The methods that may be called by tool agents are made available in a ToolAgentContext (see Section A.3.11, “Interface ToolAgentContext”). Tool agents that want to use this context must implement the interface ContextRequester (see Section A.3.4, “Interface ContextRequester”) and will receive the context before method invoke is called^[13].

As tool agents run in the application server context, they can always access the application server's JNDI directory using "new InitialContext()". This context provides all global entries (including those restricted to local access from within the JVM, i.e. "java:...").

Sometimes it may be desirable to use logical names as provided for EJBs ("java:comp/env/...") instead of global names. This may facilitate deployment, because the mapping of the logical names used by the tool agents to global names can be administered in the same way as e.g. for mapping data sources used by EJBs.

While tool agents are not EJBs themselves, WfMOpen guarantees that tool agents run in the context of a business method of the InvocationHelperEJB. Tool agents can therefore additionally lookup via JNDI all entries that are bound to the "java:comp/env/" namespace of the InvocationHelperEJB. To provide a logical name for use by a tool agent, it is therefore sufficient to add the required entry to the InvocationHelperEJB's section in ejb-jar.xml. We recommend to put entries created in this namespace for the sole use of a tool agent in a subcontext "java:comp/env/toolagents/agent name/...".

The import format for process definitions is XPDL which stands for "XML Process Definition Language". XPDL is a WfMC standard that is currently available as version 1.0 Final Draft.

When using the XPDL and the OMG API together, attention has to be payed to the usage of some keywords. The most prominent among those is the usage of the attribute Id in XPDL vs. the usage of a key in the OMG API.

Ids are used in the XPDL to enable references between the different items defined. They have no significance to the OMG API (with one exception, see below). The OMG API uses keys to uniquely identify instances within their context. So an activity with key "a23" could e.g. be the instance of an activity that was defined in the XPDL with Id="do_this".

The one exception where Ids have significance in our implementation of the OMG API is the process type. The OMG defines a process manager and this process manager has a "name" attribute denoting the process type. Currently, we use the Id from the XPDL as the process manager name (this may, however change in future versions).

It is important to maintain a clean separation between the usage of Id and key when programming against the workflow API. This is sometimes especially difficult, because keys are often labeled as "ids" in the user interface.

One of the most annoying problems with the current version of XPDL is the schema defined for InitialValue and ActualParameter tags. Although XPDL introduces a SchemaType, initial values and actual parameters may only be of type string, thus prohibiting the usage of structured data.

We have therefore defined that the content of the InitialValue of a DataField of type SchemaType is parsed as XML and used to initialize the data field. The XML may have multiple top nodes, i.e. a data field may be used to hold "lists"^[15]. The XML must be self-contained, i.e. if you use namespaces they have to be declared within the string, namespaces of the XML surrounding InitialValue are not inherited.

Starting with version 1.3.4, WfMOpen supports E4X, the XML extension for JavaScript. E4X introduces the XML "native" type (similar to e.g. the JavaScript native "Date" type) and extends the JavaScript lexical grammer to directly support XML text as initializers for new objects of this type. With E4X, parsable XML within JavaScript simply yields a new XML object. Therefore, no special provisions have to be taken to support actual parameters of SchemaType. An actual parameter specified as <ActualParameter><![CDATA[<Hello/>]]></ActualParameter> is passed to the JavaScript interpreter like any other actual parameter expression and evaluates to an XML object that is used when invoking the tool or sub-process. The XML may also have multiple top nodes. This can be expressed in E4X as e.g. <ActualParameter><![CDATA[<><Hello/><World/></>]]></ActualParameter>.

Note that the JavaScript expression need not be literal XML. It may be an arbitrarily complex JavaScript that ends with an expression of type XML. The use of complex scripts as actual parameters is, however, discouraged. A useful alternative to literal XML is e.g. the selection of a subtree from a process data item of SchemaType, such as <ActualParameter>purchaseOrder.item.(id=5)</ActualParameter>.

For backward compatibility with WfMOpen versions prior to 1.3.4, a special rule applies. If the actual parameter starts with the string "<j:jelly"^[16], it is piped through the jelly interpreter before being passed to the invoked tool or sub-process. Within the jelly script, the process relevant data items are available as variables. These variables may not be modified (this is similar to the evaluation of an actual parameter of basic type using JavaScript). Setting a variable with the same name as a process data item will create a new variable that hides the process data item.

Besides the jelly core tags, the demo application makes the "xml" and "jsl" tags available by including the respective libraries. We consider these the only useful tags in the context of actual parameter evaluation. However, no special measures have been taken to enforce this subset. If other tag libraries are bundled with the application, these will be available as well. As with JavaScript expression, causing side-effects in actual parameter evaluation is, however, strongly discouraged.

The support for jelly in actual parameter evaluation is deprecated and will be dropped in WfMOpen 2.x.

WfMOpen attempts to parse a DeadlineCondition using the following methods:

Trying to define a process definition language that can be used for any workflow engine, the WfMC had to leave out some implementation specific details. The missing information has to be provided using vendor specific extentions. The following sections describes the extensions used by WfMOpen.

...
<Application Id="INCREMENT">
   <Description>Marking the current station within the transition path.
   </Description>
   <FormalParameters>
      <FormalParameter Id="counter" Mode="INOUT">
         <DataType>
            <BasicType Type="INTEGER"/>
         </DataType>
      </FormalParameter>
   </FormalParameters>
   <ExtendedAttributes>
      <ExtendedAttribute Name="Implementation">
          <vx:ToolAgent 
            xmlns:vx="http://www.an.danet.de/2009/XPDL-Extensions1.1"
            Class="de.danet.an.workflow.tools.rhino.JSExecutor"
            Execution="SYNCHR"
            XMLParamterMode="USE_W3C_DOM">
          <vx:Property Name="Script"><![CDATA[
            java.lang.System.out.println ("Incrementing counter " 
               + args["counter"]);
            args["counter"] = args["counter"] + 1
           ]]></vx:Property>
           </vx:ToolAgent>
      </ExtendedAttribute>
   </ExtendedAttributes>
</Application>

...
          <vx:ToolAgent ... >
            <vx:ExceptionMappings>
              <vx:ExceptionMapping JavaException="java.lang.Exception"
                                   ProcessException="Error"/>
            </vx:ExceptionMappings>
          <vx:Property Name="Script"> ...

...
<package>
  ...
  <WorkflowProcesses>
    <WorkflowProcess>
      ...
      <Activities>
        ...
      </Activities>
      <ExtendedAttributes>
        <ExtendedAttribute Name="RemoveClosedProcess" Value="MANUAL"/>
        <ExtendedAttribute Name="Debug" Value="True"/>
        <ExtendedAttribute Name="AuditEventSelection" Value="AllEvents"/>
        <ExtendedAttribute Name="StoreAuditEvents" Value="True"/>
      </ExtendedAttributes>
    </WorkflowProcess>
  </WorkflowProcesses>
  <ExtendedAttributes>
    <ExtendedAttribute Name="RemoveClosedProcess" Value="AUTOMATIC"/>
  </ExtendedAttributes>
</package>
...

The definition and interpretation of the priority of a WfExecutionObject (e.g. a Process) differs between WfMC and OMG. According to WfMC, the priority can be any natural number starting with zero and higher numbers represent higher priorities. Conforming to the OMG specification, the priority has to be an integer between 1 to 5 with 1 being the highest priority. We have chosen to support OMG's specification which means that the priority specified in the process XPDL must be an integer value between 1 and 5 with descending priority and the result of a priority request (see priority()) delivers the priority with equal semantic.

Since it is not defined how to obtain the category of the process manager from the XPDL description, we have chosen to interpret the package's Name attribute as being the category value. The same applies to the version attribute, which we have chosen to map to the element created within the process header definition.

Please note, that if you don't specify the script type for you package, it will default to "text/ecmascript" which is the most common used language for scripting within this context.

Since XPDL does not define attributes for marking the first or last activity within a workflow, we have chosen to use those activities to be initially started which are not referenced within a "to" declaration of any of the workflow's transitions. We think this is an obvious approach that does not restrict the number of inital activities. Usually there will be only one entry activity but you may also define several one's which will then be started concurrently. That implies, that there has to be at least one of those activities or nothing will be started at all (in fact, a warning will report such a condition on import of the workflow description).

The workflow engine considers a running process as finished when there is nothing more to do, i.e. when after the completion of an activity there is no other activity currently running and no other activity to start (for a detailed description of process and activity states see Section 2.1, “States of processes and activities”).

The simplest case of a workflow is one with just a single activity, thus defining the start and end point. As soon as a second activity is added that should run after the completion of the first, a transition between the two activities has to be defined. A transition has a "from" and a "to" attribute, referencing start and target of the connection. Once the "from" activity is completed, the "to" activity is started (assuming there are no conditions defined).

In real life, workflows do not just incorporate activities that will be started one after the other but there may be activities to be started concurrently or choices of activities depening on certain conditions.

There are typically two different situations to be dealt with when there is more than one subsequent activity:

The workflow engine expects a boolean to be returned. That means, if more than one line of code is defined only the last one defines the condition. Prior statements may be used e.g. for debugging purposes. Note that conditions are evaluated exactly once when the "from" activity is completed.

Example:

 
	  ...
	    <Condition Type="CONDITION">
	      java.lang.System.out.println ("counter is " + Counter);
	      Counter &lt; 3
            </Condition>
	  ...
	  

Since XOR-Splits are used to select one of many activities although more than one of the given condition may evaluate to "true", an evaluation order has to be defined. This is done within the TransitionRestrictions of the activity. As soon as the first condition matches, this transition is chosen, the target activity is started and no further evaluation is performed.

Figure 4.1. XOR-Split example

 
...
<WorkflowProcess Id="XorSplitSample">
  <ProcessHeader/>

  <DataFields>
    <DataField Id="avg_payroll" IsArray="FALSE">
      <DataType>
        <BasicType Type="INTEGER"/>
      </DataType>
    </DataField>
    <DataField Id="test_payroll" IsArray="FALSE">
      <DataType>
        <BasicType Type="INTEGER"/>
      </DataType>
    </DataField>
  </DataFields>

  <Activities>
    <Activity Id="check_payroll">
      <Implementation>
        <No/>
      </Implementation>
      <TransitionRestrictions>
        <TransitionRestriction>
          <Split Type="XOR">
            <TransitionRefs>
              <TransitionRef Id="granted"/>
              <TransitionRef Id="declined"/>
            </TransitionRefs>
          </Split>
        </TransitionRestriction>
      </TransitionRestrictions>
    </Activity>
    <Activity Id="decline_salary_increase">
      <Implementation>
        <No/>
      </Implementation>
    </Activity>
    <Activity Id="accept_salary_increase">
      <Implementation>
        <No/>
      </Implementation>
    </Activity>
  </Activities>
  
  <Transitions>
    <Transition Id="declined" From="check_payroll" To="decline_salary_increase">
      <Condition Type="OTHERWISE"/>
    </Transition>
    <Transition Id="granted" From="check_payroll" To="accept_salary_increase">
      <Condition Type="CONDITION">
       avg_payroll &lt; test_payroll
      </Condition>
    </Transition>
  </Transitions>
</WorkflowProcess>
...

For AND-Splits no evaluation order is needed, since each transition with a condition evaluating to "true" is chosen and the target activity is started. Note that the workflow engine will start each of those activities in a different thread so that they are performed simultaneously.

As for splitting there a also typically two different situations to be dealt with when joining parallel activities into a common thread:

Since predecessing activities and the joining activity are connected via transitions, you may also define conditions here that will be evaluated before triggering. So, within an XOR-Join, the first completed activity with a matching condition will trigger the joining activity. Note that, in contrast to the XOR-Split, no evaluation order is needed here since it is defined implicitely by the the race condition of the activites. Once the second of the predecessing activities is completed, the engine will detect that the joining activity is (no longer) in state "not started" and thus do nothing with it.

A special case of join occurs, when a predecessing activity is at the same time a subsequent activity of the joining activity. This situation describes a loop within a workflow which will be discussed in more detail in the following section.

Condition evaluation for outgoing transitions takes place when an activity transitions to the closed... state. This is important to know in order to understand the behaviour of activities that use AND-Join.

If such an activity has two incoming transitions from e.g. activities pre1 and pre2 it may happen that pre1 reaches its closed state long before pre2. If the transition from pre1 has a condition that depends on some process relevant data item, the value of this data may have changed after pre1 has reached the closed state but before pre2 finishes. According to the definiton above, the condition will be evaluated based on the value at the time when pre1 reaches the closed state, subsequent changes of the process relevant data will not change the result of this evaluation^[18].

Looping within a workflow means that the workflow comes back to an activity that has already been completed before. WfMOpen supports loops in a very straightforward way and without limitations concerning start and end points of loops^[19].

There is no special attribute defining an activity or transition being part of a loop. Rather the workflow engine of WfMOpen detects a loop by tracking the running workflow. As soon as a transition targets an activity that has already been marked as "been on the path", this activity is considered as entry point of a loop (the activity must, of course, have an XOR-Join mode).

If the target activity is completed, the workflow engine first resets the state of all activites on the path that lead to that activity to "not started" and the (re-)starts the target activity.

Asynchronous deadlines constitute new independant threads. Thus the activity started by the deadline has an empty path. You can therefore not loop back to the activity that defined the deadline. You can loop back to the activity started by the asynchronous deadline e.g. to have it re-triggered by a later deadline (though you'll need an extra route activity because of join conditions).

Synchronous deadlines continue processing using the same thread. Thus all activities that have been adandoned due to the deadline are predecessors of the activity started because of the deadline (there may be more than one activity that is abandoned because of the deadline if the deadline occurs on a block activity). The simplest usage of this behaviour may be a synchronous deadline that points back to the synchronous activity, thus causing a maybe different assignment of resources.

WfMOpen supports the "deferred choice" pattern as described on the workflow patterns site. The pattern is implemented by defining an optional extended attribute for activities with an AND-split. E.g.:

...
<Activity Id="act1" Name="ACT1">
  <Implementation>
    <No/>
  </Implementation>
  <StartMode>
    <Automatic/>
  </StartMode>
  <FinishMode>
    <Automatic/>
  </FinishMode>
  <TransitionRestrictions>
    <TransitionRestriction>
      <Split Type="AND"/>
    </TransitionRestriction>
  </TransitionRestrictions>
  <ExtendedAttributes>
    <ExtendedAttribute Name="DeferredChoice">true</ExtendedAttribute>
  </ExtendedAttributes>
</Activity>

All activities following the activity with the deferred choice option set are started "preliminary". The activity (or tool started by the activity) that first performs a modification of the workflow engine's state automatically becomes the chosen activity. Modification of state includes a tool's calls to setResult() and complete(), the completion of an activity that has no implementation and the termination and abandoning of an activity. All other preliminary chosen activities are reset to the "not started" state (see Section 2.1, “States of processes and activities”) after terminating any tools that are being run by these activities.

The preliminary choice implies the possibility that a tool executed by an activity has already performed some work that cannot be rolled back when the preliminary choice is revoked, i.e. in the tool's implementation of terminate(). A "deferred choice aware" tool may therefore prematurely (i.e. before calling setResult() or complete()) force the eventual choice to be made by calling choose() on the activity (see choose()). An example of such a case would be a user front-end where the selection of an assigned activity (i.e. the begin of work) is already decisive for the continuation of the process. If not invoked as part of a deferred choice, the call to choose() simply does nothing.

If an activity requires human interaction such as providing some data in a form, the activity may submit a form and associated initial data to the XForms tool. Then, the user associated with the activity invokes the XForms tool in order to manually complete the activity.

The XForms tool is an example of asynchronous application invocation and therefore consists of two components. The first component, the tool agent, is invoked by the workflow engine and puts information about the form to complete and the assignee in the database. The second component, the actual application, consists of a portlet. Initially, it lists all activities assigned to the currently logged in user. The display distinguishes between activities that are directly assigned to the current user and activities that are indirectly assigned, i.e. that are assigned to groups or roles the current user belongs to.

Figure 5.1. XForm task list

The web form for a specific activity is selected and displayed by selecting the link in the "Activity" column. The form may then be used to enter the required data. When the form is submitted, the entered data is used as result data of the activity and the activity is set to state "completed".

Figure 5.2. XForm sample

An application of type "XFormTool" is specified in the process definition as described in Section 4.2.5.1, “Extentions of Application Declaration”, with the extended attribute Implementation referencing the class de.danet.an.xformstool.Submitter.

The tool agent has a mandatory property named Form that defines the XForm (see XForms specification) to display.

A complete example of such an application definition is shown below:

...
<Application Id="SimpleForm">
  <Description>
    Simple data form.
  </Description>
  <FormalParameters>
    <FormalParameter Id="input" Mode="OUT">
      <DataType><BasicType Type="STRING"/></DataType>
    </FormalParameter>
  </FormalParameters>
  <ExtendedAttributes>
    <ExtendedAttribute Name="Implementation">
      <vx:ToolAgent Class="de.danet.an.xformstool.Submitter"
        Execution="SYNCHR">
        <vx:Property Name="Form">
          <html xmlns="http://www.w3.org/1999/xhtml"
            xmlns:xforms="http://www.w3.org/2002/xforms"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema">
            <head>
              <title>Simple Form</title>
              <style>
                .SimpleForm .control { display:block; }
                .SimpleForm .control label { 
                   display:block; float:left; width:9em; }
              </style>
              <xforms:model>
                <!-- Instance will be inserted here -->

                <!-- override/add some bindings -->
                <xforms:bind id="SimpleForm:input" 
                  nodeset="ActualParameter[@name='input']"
                  constraint="string-length(.) &gt; 0"
                  required="true()"/>
              </xforms:model>
            </head>
            <body class="SimpleForm">
              <xforms:group id="C-3" appearance="minimal">
                <xforms:label id="C-4">Simple Form</xforms:label>
                <xforms:input bind="SimpleForm:input" incremental="true">
                  <xforms:label>Input </xforms:label>
                  <xforms:alert>Field may not be empty!</xforms:alert>
                  <xforms:hint>Please enter something.</xforms:hint>
                  <xforms:help id="C-7h">Use the <b>keyboard</b>.</xforms:help>
                </xforms:input>
                <xforms:submit submission="action">
                  <xforms:label>Complete</xforms:label>
                </xforms:submit>
              </xforms:group>
            </body>
          </html>
        </vx:Property>
      </vx:ToolAgent>
    </ExtendedAttribute>
  </ExtendedAttributes>
</Application>
...

The form definition consists of XHTML and XForms elements. It must have an <xhtml:html> as root element. The nested <xhtml:head> may have a <xhtml:title>. If specified, it is displayed as title of the portlet when the form is selected and displayed. Any specified styles are copied to the the portal page^[21]. To avoid ambiguities between forms display in different portlets on the same page, the style declarations should be made unique by starting the match expression with the application's id as a class. The HTML rendered for the form in the portlet will have an enclosing <div> with the application's id as class attribute. CSS styles specified with this class name in the match expression will therefore only apply to this form and no other form on the same portal page.

As last child of <xhtml:head>, the tool automatically generates and inserts an XForms model derived from the formal parameters. The model looks like this:

<xforms:model>
  <instance xmlns="">
    <ActualParameters xmlns="">
      <ActualParameter name="input"/>
    </ActualParameters>
  </instance>
  <submission xmlns="http://www.w3.org/2002/xforms" 
    action="invoke:application" id="action" method="" replace="none"/>
  <xforms:bind id="SimpleForm:input" 
    nodeset="ActualParameter[@name='input']"/>
</xforms:model>

Finally, the form defines the <xhtml:body> with the actual GUI elements. The form is processed with Chiba XForms processor (see Chiba home page). See the Chiba documentation for details about how HTML generated from the XForm definition.

The first formal parameter of a Jelly tool declaration must be an OUT parameter of SchemaType. It receives the result, i.e. the generated XML. The other formal parameters of the tool invocation may be of arbitrary type and are directly available as variables within the Jelly script. Values assigned to variables that correspond to formal OUT or INOUT parameters in the Jelly script will change the values of the actual parameters upon tool completion.

Its SQL library makes Jelly the perfect tool for interfacing between XML data structures and an RDBMS. The library provides the same tags as the JSTL SQL tag library. The sample script below retrieves the names of the process definitions from the Workflow engine's database^[23].

 ...
<Application Id="DBJelly">
  <Description>Database Jelly test</Description>
  <FormalParameters>
    <FormalParameter Id="result" Mode="OUT">
      <DataType>
        <SchemaType/>
      </DataType>
    </FormalParameter>
  </FormalParameters>
  <ExtendedAttributes>
    <ExtendedAttribute Name="Implementation">
      <vx:ToolAgent Class="de.danet.an.workflow.tools.JellyTool">
        <vx:Property Name="Script">
          <j:jelly trim="false" xmlns:j="jelly:core" xmlns:x="jelly:xml" 
            xmlns:html="jelly:html" xmlns:sql="jelly:sql"
            xmlns:sqlx="jelly:de.danet.an.util.jellytags.Library">
            <sql:setDataSource dataSource="jdbc/WfEngine"/>

            <sqlx:query var="results">
              SELECT PackageId, ProcessId FROM ProcessDefinition 
              WHERE PackageId = ?
              <sql:param value="jellytests"/>
            </sqlx:query>

            <dataSet>
              <j:forEach items="${results.rowsByIndex}" var="row">
                <row>
                  <j:forEach var="columnName" 
                    items="${results.columnNames}" indexVar="i">
                    <field column="${columnName}">${row[i]}</field>
                  </j:forEach>
                </row>
              </j:forEach>                  
            </dataSet>
          </j:jelly>
        </vx:Property>
      </vx:ToolAgent>
    </ExtendedAttribute>
  </ExtendedAttributes>
</Application>
...

The example script uses a special query tag. This tag uses a PreparedStatement wrapper from the Danet utility library that handles large strings correctly even if you use Oracle as RDBMS. A similar update tag is available in the namespace jelly:de.danet.an.util.jellytags.Library as well.

Although it is possible to define "stand-alone" data sources for your RDBMS using the SQL tag library, it is much better to use the pooled connections managed by the application server. The SQL tag library supports access to these pools via JNDI, as shown in the example. Note that "java:comp/env/" is prepended before the data source name (so the lookup made in the sample code is "java:comp/env/jdbc/WfEngine"). The data source must therefore be defined as a logical name in an EJB context. All tools are invoked from a business method of the InvocationHelperEJB. Therefore, if you need additional data sources, you have to define them in this EJB's context (either by modifying ejb-jar.xml and its associated application server specific descriptor manually or by using some tool from your application server vendor).

As the tool is executed in the context of an EJB's business method, the <transaction> tag should not be used. The business method that invokes the tool has the container managed transaction attribute set. Thus the application server automatically wraps all database queries and updates executed during the tool invocation in a transcation.

Note that there are a lot of tag libraries available for Jelly. Some of these interface to quite complex libraries. The demo applications (see Appendix C, The demo applications) includes only the tag libraries "jsl", "log", "sql", and "xml". Of course, you are free to re-pack the application with more libraries included.

Thinking about an LDAP tool, we found that a query tool can be implemented in a straight forward manner. A tool that also supports LDAP manipulation, however, would require an unmanageable number of configuration properties to support the different kinds of queries imaginable. We have therefore implemented an LDAP tag library for Jelly that enables easy query and manipulation of an LDAP directory.

<ldap:setInitialContext 
    var="ctx" 
    xmlns:ldap="jelly:de.danet.an.util.jellytags.ldap.Library"
    providerUrl="ldap://localhost:389" 
    securityPrincipal="cn=Manager,dc=my-domain,dc=com">
    <ldap:environmentEntry name="java.naming.security.credentials" 
        value="${credential}"/>
</ldap:setInitialContext>

<ldap:query ldapContext="${ctx}"
   dn="ou=People,dc=my-domain,dc=com" 
   filter="(uid=lipp)" attributes="cn, uid,gecos"/>

<queryResult dn="ou=People,dc=my-domain,dc=com"
    filter="(uid=lipp)">
  <entry dn="uid=lipp,ou=People,dc=my-domain,dc=com">
    <attribute name="gecos">Michael N. Lipp</attribute>
    <attribute name="uid">lipp</attribute>
    <attribute name="cn">Michael N. Lipp</attribute>
  </entry>
</queryResult>

<Application Id="LDAPQuery">
 <Description>Query fixed entry</Description>
 <FormalParameters>
  <FormalParameter Id="result" Mode="OUT">
   <DataType>
    <SchemaType/>
   </DataType>
  </FormalParameter>
 </FormalParameters>
 <ExtendedAttributes>
  <ExtendedAttribute Name="Implementation">
   <vx:ToolAgent Class="de.danet.an.workflow.tools.JellyTool">
    <vx:Property Name="Script">
     <j:jelly trim="false" xmlns:j="jelly:core" xmlns:x="jelly:xml" 
      xmlns:html="jelly:html" xmlns:log="jelly:log"
      xmlns:ldap="jelly:de.danet.an.util.jellytags.ldap.Library">
      <!-- You will probably not put this in the process description. 
      Use Jelly functions to obtain the password from e.g. JNDI 
      environment, a properties file or whatever password store suits
      your application. -->
      <j:set var="credential" value="********"/>
      
      <!-- ldap:setInitialContext supports attributes
      "initialContextFactory", "providerUrl", "securityPrincipal"
      and "securityCredentials" as short-cuts.
      More entries may be set in the environment used by using nested
      "environmentEntry" tags, as shown. -->
      <ldap:setInitialContext var="ctx" providerUrl="ldap://localhost:389" 
       securityPrincipal="cn=Manager,dc=my-domain,dc=com">
       <ldap:environmentEntry name="java.naming.security.credentials" 
        value="${credential}"/>
      </ldap:setInitialContext>
      
      <!-- Execute the query and save the result document -->
      <x:parse var="response">
       <ldap:query ldapContext="${ctx}" dn="ou=People,dc=my-domain,dc=com" 
        filter="(uid=lipp)" attributes="cn, uid,gecos"/>
      </x:parse>
      
      <!-- Output the user record -->
      <x:set var="userId" select="$response/queryResult/entry/@dn" 
       single="true" asString="true"/>
      <x:set var="userName" 
       select="$response/queryResult/entry/attribute[@name='cn']" 
       single="true" asString="true"/>
      <user id="${userId}" name="${userName}"/>
     </j:jelly>
    </vx:Property>
   </vx:ToolAgent>
  </ExtendedAttribute>
 </ExtendedAttributes>
</Application>

<ldap:insert ldapContext="${ctx}">
  <entry dn="uid=test,ou=People,dc=my-domain,dc=com">
    <attribute name="objectClass">top</attribute>
    <attribute name="objectClass">account</attribute>
    <attribute name="description">Just a test account</attribute>
  </entry>
</ldap:insert>

<ldap:update ldapContext="${ctx}" operation="replace">
  <entry dn="uid=test,ou=People,dc=my-domain,dc=com" 
    operation="replace">
    <attribute name="description" operation="replace">
     Just an updated test account
    </attribute>
    <attribute name="organizationName">Testing</attribute>
  </entry>
</ldap:update>

<ldap:delete ldapContext="${ctx}">
  <entry dn="uid=test,ou=People,dc=my-domain,dc=com"/>
</ldap:delete>

The receiver tool receives messages from a channel. It takes an IN parameter of type STRING that specifies the channel to listen on, and an arbitrary number of additional OUT parameters that receive the data sent on the channel. The formal parameter names must match the keys used in the map passed to the channel by the client (see sendMessage(java.util.Map)).

Normally, the receiver receives messages sent to the process it was started in. Sometimes, however, it is useful to structure a workflow process by using subflows. If the activities separated into the subflow include the usage of a receiver tool, the receiver tool listens on the wrong process, as the client does not (and should not) know about the separation in main process and subflow and keeps sending the messages to the main process.

The receiver tool therefore has a property "ListenerIndex" that can be used to make the receiver listen for messages sent to one of the requesting processes of the current process (i.e. processes the current process is a subflow of). If set, the property must be an integer. 0 (zero) is the top requester, i.e. the process at the end of the chain of requesting processes^[26]. A positive integer specifies a process relative to the current process (e.g. "1" is the requester, "2" is the requester of the requester) while a negative integer specifies a subflow relative to the top process.

Example:

...
    <Application Id="TopReceiverTool">
      <Description>Receive data from a channel accessor</Description>
      <FormalParameters>
	<FormalParameter Id="channel" Mode="IN">
	  <DataType>
	    <BasicType Type="STRING"/>
	  </DataType>
	</FormalParameter>
	<FormalParameter Id="message" Mode="OUT">
	  <DataType>
	    <BasicType Type="STRING"/>
	  </DataType>
	</FormalParameter>
      </FormalParameters>
      <ExtendedAttributes>
	<ExtendedAttribute Name="Implementation">
	  <vx:ToolAgent Class="de.danet.an.workflow.tools.chabacc.Receiver"
            xmlns:vx="http://www.an.danet.de/2009/XPDL-Extensions1.1">
	    <vx:Property Name="ListenerIndex">0</vx:Property>
	  </vx:ToolAgent>
	</ExtendedAttribute>
      </ExtendedAttributes>
    </Application>
...

The sender tools sends messages on a channel. It takes an IN parameter of type STRING that specifies the channel to send to, and an arbitrary number of additional IN parameters used to pass the data to be sent to the channel. The formal parameter names are used as keys in the map returned to the client (see receiveMessage()). Note that actual parameters are sent on the channel as passed to the sender tool. This implies that parameters of type SchemaType may be sent as SAX event buffer, W3C DOM or JDOM, depending on the value of attribute XMLParameterMode in the definition of the sender tool (see Section 4.2.5.1, “Extentions of Application Declaration”).

Like the receiver tool, the sender tool may be configured to send messages from a requesting process instead of the process the tool was started in. This is done by setting the property "OriginatorIndex". The value is interpreted in the same way as described for the receiver tool above.

An additional property of the sender tool specifies whether messages sent should also be delivered to receiver tools listening on the channel used (by default, they are only delivered to clients). This may e.g. be used at the end of a process to terminate a receiver tool running "in parallel" (i.e. it has waited for some kind of optional intervention from a client during processing and is now sent some dummy message to complete the process properly). Together with the "ListenerIndex" and "OriginatorIndex" properties, this may also be used for communication between processes, e.g. a subflow informing its requester about its state.

Example:

...
    <Application Id="TopSenderTool">
      <Description>Send a message to a channel accessor</Description>
      <FormalParameters>
	<FormalParameter Id="channel" Mode="IN">
	  <DataType>
	    <BasicType Type="STRING"/>
	  </DataType>
	</FormalParameter>
	<FormalParameter Id="message" Mode="IN">
	  <DataType>
	    <BasicType Type="STRING"/>
	  </DataType>
	</FormalParameter>
      </FormalParameters>
      <ExtendedAttributes>
	<ExtendedAttribute Name="Implementation">
	  <vx:ToolAgent Class="de.danet.an.workflow.tools.chabacc.Sender"
            xmlns:vx="http://www.an.danet.de/2009/XPDL-Extensions1.1">
	    <vx:Property Name="LocalDelivery">True</vx:Property>
	    <vx:Property Name="OriginatorIndex">0</vx:Property>
	  </vx:ToolAgent>
	</ExtendedAttribute>
      </ExtendedAttributes>
    </Application>
...

To simplify the HTTP access to a longterm workflow process, as it may be useful for designing dialog driven applications, an "out-of-the-box" solution is provided by a generic HTTP servlet.

For an example, let us assume we'd like to design an application that enables users to subscribe and unsubscribe a service and to modify the service parameters. The user interface should be provided by HTML pages and the service will be described by a workflow process definition^[27].

The components we need are:

Subscribing to a new service is easy to implement, since it may simply be done by starting a new workflow process. But once the process is running, arrangements have to be made to make sure that the process performs its service duties and concurrently listens for service "update" events. The latter task can be performed using the Receiver Tool (see Section 5.12.1, “Receiver tool”) and the Sender Tool (see Section 5.12.2, “Sender tool”) within a concurrently running activity.

To simplify the (channel based) interaction with workflow processes via HTTP, a servlet is provided that

By using this servlet, HTTP based client applications (e.g. using HTML pages) are very easy to design. The current page sends a request to the servlet and the successor page (code) is provided by the proper workflow activity through the servlet. No further application code is needed.

The servlet described above serves as an interface between the client application and a workflow process. The communication with the process uses a message channel named "initiator") ^[28].

To identify the process to connect with, some key information has to be provided within the request. The following request parameters are treated as key values:

Variations:

The message received on the channel from the process (sent by the process using the sender tool, see Section 5.12.2, “Sender tool”) may have one or more entries. If it has only a single entry, this entry is considered to be the data to be sent back to the HTTP client, independant of the entry's name. If the message has more than one entry, there must be one entry with key data containing the data to be sent back or otherwise, status 500 will be returned to the client. The data (i.e. the corresponding formal parameter of the SenderTool) may be of type STRING or SchemaType. In the latter case, the XML data is transformed to its string representation by the generic HTTP servlet before it is sent to the HTTP client. Note that the data must be provided as a SAX buffer, i.e. the sender tool defined for sending the response to the servlet must have the attribute XMLParameterMode set to USE_SAX (see Section 4.2.5.1, “Extentions of Application Declaration”).

Additional entries supported in a message received by the generic HTTP servlet are:

The generic HTTP servlet will accept POST requests only, as all requests lead to a modification of the server side state. There is, however, one exception to this rule.

In order to get started with a process based Web application, you must present the user an initial page that allows him to click on a link to create a new process or to fill in and submit some information that identifies an existing process. Now, where does this start page come from? Of course, it can simply be created as static HTML and provided by any Web server (and for performance reasons, this will eventually be the solution in many cases). However, even if only as proof of concept, it should be possible to specify a complete Web application — including the start page — using XPDL.

As initial URLs (i.e. URLs that can be typed into a browser) will always perform a GET request, the generic HTTP servlet must support such a request for generating the start page. As this is a "get started" request, it will always create a new process, whose single purpose is to send back the content of the start page and then complete ^[29] (although there may be cases that allow to continue the lifespan of this process). To avoid complicated looking URLs, the generic HTTP servlet uses extra path information instead of parameters to specify the type (i.e. package id and process id) of the process to be created. The first segment in the extra path information denotes the package id, the second the process id. If the process id is omitted, it defaults to boot, if the package id is omitted also, it defaults to chabacc_http_plain. Both defaults may be altered by specifying the servlet init parameters packagePathSegmentDefault and processPathSegmentDefault respectively.

Some examples of using the generic HTTP servlet are included in the demo applications (see Appendix C, The demo applications).

Unless a standards based approach is used (see below) user information is most likely kept in an RDBMS. WfMOpen therefore includes a generic implementation of a database based RMS that can be adapted to a wide range of database schemas.

The detailed description of this service and its configuration parameters can be found in de.danet.an.workflow.rmsimpls.dbrms.

The factory and service classes are bundled in the de.danet.an.workflow.dbrms.jar which can be found in $DIST/lib/wfcore/. Besides the required classes, this jar contains the file META-INF/services/de.danet.an.workflow.spis.rms.ResourceManagementServiceFactory that defines the class de.danet.an.workflow.rmsimpls.dbrms.DatabaseRmsFactory as an implementation of the resource management service. Thus the database based resource management service is found as described in newInstance() if the jar is included in the classpath of the EAR that comprises the application. Usually, this is done by adding the jar as Java module to application.xml.

The service must be configured by specifying the statements for the various resource queries. This is decribed in detail in de.danet.an.workflow.rmsimpls.dbrms.DatabaseRmsFactory.

In general, information about resources is often kept in Enterprise Information Systems (EIS). The preferred approach for accessing this kind of systems in J2EE is by using JCA. WfMOpen therefore provides a resource management system implementation that relies on a JCA datasource to obtain information about resources.

<?xml version="1.0" encoding="ISO-8859-1"?>

<!-- The properties based RMS resource adaptor service configuration -->
<connection-factories>
  <no-tx-connection-factory>
    <jndi-name>DefaultWfMOpenRmsRA</jndi-name>
    <rar-name>
      de.danet.an.plutoportalapp.ear#de.danet.an.workflow.propsrmsra.rar
    </rar-name>
    <connection-definition>
      de.danet.an.workflow.rmsimpls.eisrms.aci.RmsConnectionFactory
    </connection-definition>
    <config-property name="PropertiesDirUrl" type="java.lang.String">
      ${jboss.server.config.url}
    </config-property>
    <config-property name="UsersPropertiesFile" type="java.lang.String">
      wfdemopluto-users.properties
    </config-property>
    <config-property name="RolesPropertiesFile" type="java.lang.String">
      wfdemopluto-roles.properties
    </config-property>
    <config-property name="GroupsPropertiesFile" type="java.lang.String">
      wfdemopluto-groups.properties
    </config-property>
  </no-tx-connection-factory>
</connection-factories>
            

<?xml version="1.0" encoding="ISO-8859-1"?>

<!-- The properties based RMS resource adaptor service configuration -->
<connection-factories>
  <no-tx-connection-factory>
    <jndi-name>DefaultWfMOpenRmsRA</jndi-name>
    <rar-name>
      de.danet.an.plutoportalapp.ear#de.danet.an.workflow.ldaprmsra.rar
    </rar-name>
    <connection-definition>
      de.danet.an.workflow.rmsimpls.eisrms.aci.RmsConnectionFactory
    </connection-definition>
    <config-property name="UserCtxDN" type="java.lang.String">
      ou=People,dc=my-domain,dc=com
    </config-property>
    <config-property name="GroupCtxDN" type="java.lang.String">
      ou=ResourceGroups,dc=my-domain,dc=com
    </config-property>
    <config-property name="RoleCtxDN" type="java.lang.String">
      ou=ResourceRoles,dc=my-domain,dc=com
    </config-property>
  </no-tx-connection-factory>
</connection-factories>
            

The implementation of NewDefinitionRq differs from the specification. If the factory exists, the process definition will be overwritten without warning. It is also possible to create multiple factories using a single request. Neither the ASAP specification nor the Wf-XML specification consider the deletion of processes. Using this approach it is possible to delete processes within a package by simply overwriting the package definition.

The implementation of GetProperties produces XML that fails validation, since the Wf-XML schema definition is erroneous at this point. The ASAP schema defines groups for Instance, Factory, and Observer. Wf-XML defines new groups for the ServiceRegistry and the Activity resources, which are not referenced by GetPropertiesRs, since this is specified in the ASAP schema, and which does not know about any extensions. As a consequence the new groups for the Service Registry and the Activity resource must not be a part of a GetPropertiesRs message.

The specification mentions that a ListDefinitions may contain filters, i.e. Name and Status. These filters are missing in the schema definition and are not implemented. However, filtering of factories might make sense, but more in terms of the package and process ids, rather than the name, which might be ambivalent.

SetDefinition is not implemented. As a workaround, NewDefinition of ServiceRegistry can be used instead, see above.

TerminateRq is not implemented, since the specification for this request in the ASAP schema is missing. The Wf-XML specification refers to the ASAP specification for this request, but it is not mentioned there. As a workaround it is possible to use a ChangeStateRq instead.

The SubscribeRq request allows to receive notification messages, if the process state changes. The ASAP specification is not precise at this point. The implemented behavior for these critical points is described below.

The implementation of GetProperties produces XML that fails validation caused by an error in the Wf-XML schema as it is described for the Service Registry.

For GetProperties the field DueDate contains a timestamp that matches Long.MAX_VALUE, since this date is currently not available using the API.

The portlet application is packaged as a self-contained WAR, i.e. it includes all libraries, resources etc. required to run the portlet in an JSR-168 compliant portal.

The only (obviously) missing libraries are the client libraries of the application server that runs the workflow engine. These libraries are required by the portlets to contact the workflow engine. We assume that these libraries are made available in the portal as a shared resource, not on a per-portlet application base. If the runtime environment of the portal is an application server (not just a servlet container), this is usually the case by default. If the portal runs e.g. in Tomcat, the application server's client libraries should be copied to $CATALINA_HOME/shared/lib.

Unless the portal and the workflow engine run in the same application server, the portlets need some information to lookup the JNDI service of the application server that runs the workflow engine. The preferred way to configure the JNDI server is adding environment entries to the portlet application's web.xml as described in newInstance(). The propagation of the security identity in call to the workflow engine is left to the portlet container as described in the "Java Portlet Specification" (JSR-168), section PLT.20.5 "Propagation of Security Identity in EJB Calls".

As distributed, the Jetspeed2 portal runs in the Tomcat servlet container environment (see Jetspeed2 Home Page). It therefore requires both the installation of the application server's client libraries and a configuration update to ensure security identity propagation. Both issues are described in the following section assuming that the workflow engine is deployed in JBoss.

After installation, start the portal once and shut it down again.

Now copy $JBOSS_HOME/client/jbossall-client.jar to $JETSPEED_HOME/shared/lib/. This makes the JBoss client libraries availabe to all components run in this Tomcat environment.

In $JETSPEED_HOME/webapps/jetspeed/WEB-INF/classes/ create a new file login.conf with the following contents:

Jetspeed {
   org.apache.jetspeed.security.impl.DefaultLoginModule required;
   org.jboss.security.ClientLoginModule required;
};

The line org.jboss.security.ClientLoginModule required; (added with respect to the default configuration^[33]) causes the security credentials to be propagated to invoke EJBs.