Chapter 14.  jBPM Process Definition Language

You can deploy a process archive in any of these ways:

To deploy a process archive with the Process Designer Tool, right-click on the process archive folder and select the Deploy process archive option.

The jBPM application server integration modules include the gpd-deployer web application, which has a servlet to upload process archives, called GPD Deployer Servlet. This servlet is capable of receiving process archives and deploying them to the configured database.

To deploy a process archive with an ant task, define and call the task as follows.

<target name="deploy-process">
  <taskdef name="deployproc" classname="org.jbpm.ant.DeployProcessTask">
    <classpath location="jbpm-jpdl.jar" />
  </taskdef> 
  <deployproc process="build/myprocess.par" />
</target>

To deploy more process archives at once, use nested fileset elements. Here are the DeployProcessTask attributes.

To deploy process archives programmatically, use one of the parseXXX methods of the org.jbpm.graph.def.ProcessDefinition class.

Process instances always execute on the same process definition as that in which they were started. However, the jBPM allows multiple process definitions of the same name to co-exist in the database. Typically, a process instance is started in the latest version available at that time and it will keep on executing in that same process definition for its complete lifetime. When a newer version is deployed, newly created instances will be started in the newest version, while older process instances keep on executing in the older process definitions.

If the process includes references to Java classes, these can be made available to the jBPM runtime environment in one of two ways:

When a process archive is deployed, a process definition is created in the jBPM database. Version process definitions on the basis of their names. When a named process archive is deployed, the deployer assigns it a version number. It does so by searching for the highest number assigned to a process definition of the same name and then adds one to that value. (Unnamed process definitions will always be versioned as -1.)

Consider these factors before undertaking this process:

An alternative approach to changing a process definition is to migrate each process instance to a new version. Please consider that migration is not trivial due to the long-lived nature of business processes.

There is a clear distinction between definition data, execution data and logging data. Because of this distinction, a new version of the process has to be deployed first, and then process instances are migrated to the new version. Migration involves a translation if tokens or task instances point to nodes or task definitions that have been removed in the target process definition. Be aware that logging data ends up spread over two process definitions. This can present challenges when developing tools and making statistics calculations.

To migrate a process instance to a new version, execute the ChangeProcessInstanceVersionCommand as shown below.

new ChangeProcessInstanceVersionCommand()
  .processName("commute")
  .nodeNameMappingAdd("drive to destination", "ride bike to destination")
  .execute(jbpmContext);

The jBPM class loader is the one that loads the jBPM classes. To make classes visible to the jBPM class loader, pack them in a JAR file and co-locate the JAR with jbpm-jpdl.jar. In the case of web applications, place the custom JAR file in WEB-INF/lib alongside jbpm-jpdl.jar.

Delegation classes are loaded through their respective process class loader. The process class loader has the jBPM class loader as its parent. It adds the classes deployed with one particular process definition. To add classes to a process definition, put them in the classes directory of the process archive. Note that this is only useful when you want to version the classes that have been added to the process definition. If versioning is not required, make the classes available to the jBPM class loader instead.

If the resource name does not start with a slash, resources are also loaded from the process archive's classes directory. To load resources that reside outside this directory, start the path with a double forward slash (//). For example, to load data.xml, located in the process archive root, call class.getResource("//data.xml").

Delegation classes contain user code that is called from within a process execution, the most common example being an action. In the case of action, an implementation of the ActionHandler interface can be called on an event in the process. Delegations are specified in the processdefinition.xml file. You can supply any of these three pieces of data when specifying a delegation:

Here are descriptions of every type of configuration:

public class MyAction implements ActionHandler {
  // access specifiers can be private, default, protected or public
  private String city;
  Integer rounds;
  ...
}

...
<action class="org.test.MyAction">
  <city>Atlanta</city>
  <rounds>5</rounds>
</action>
...

When parsing a jPDL XML document, jBPM will validate it against the schema when these two conditions are met: