Notes on JPDL authoring

Special considerations for workflows to be deployed in Daisy

Process definition verification

When deploying a process definition in Daisy, Daisy applies some stricter checking on the process definition than jBPM does, more specifically:

• it checks the process definition has a name

• it checks the process definition has a start-state node

• it checks all nodes in the process definition have a name

• it checks all tasks (in task-node and the start-state task) have a name

• it checks all (leaving) transitions of the nodes have names

• it validates the Daisy metadata (if present) against its XML schema

Without these names, it is hard/impossible to refer to these entities from the Daisy-specific process metadata, or from the non-Java HTTP API, or to tell the user something about them.

If any of these checks fail, an exception is thrown and the process definition is not deployed.

Give all nodes, tasks an transitions names

As a result from the above mentioned verification process, all nodes, tasks and transitions in the workflow definition should have a name. The names should follow the jBPM scoping rules for uniqueness. For tasks, this means globally unique.

Use tasks as the only wait-states that need human interaction

The Daisy frontend GUI only supports task-based signaling (triggering) of the workflow execution. On the API level it is also possible to trigger specific execution paths, though currently there is no GUI for this.

Gather initial parameters using a start-state task

If you want to gather some initial parameters for the workflow process, you can do this by associating a task with the start state. In jBPM, if the task associated with the start state is associated with a swimlane (= a process role), than that swimlane gets automatically assigned to the user starting the process, hence allowing to capture the process initiator (in order to assign future tasks to the same user).

Daisy jBPM utilities

Using Javascript in process definitions

It is possible to script actions using Javascript in process definitions. The basic syntax is as follows:

<action class="org.outerj.daisy.workflow.jbpm_util.JavascriptActionHandler">
  <script>
     /* script comes here */
  </script>
</action>

jBPM strips and collapses whitespace and newlines from the content of the <script> element. Therefore, do not use double-slash comments (// comment), since this will effectively comment out the remainder of the script.

The following variables are made available to the Javascript:

• repository: the repository object for the current user (see the Daisy API, Repository interface). In timer actions, there is no "current user", therefore use the wfRepository instead.
• wfRepository: the repository object for the "workflow" user (the actual workflow user can have any name and is configured in the myconfig.xml). This is useful for multiple purposes:
• to perform repository operations that the person who currently triggered the workflow execution isn't allowed to do (the workflow user has Administrator privileges)
• to perform repository operations that you do not want to have associated with the current user (the user might not be aware of all the execution progress it triggers throughout the workflow)
• in timers, which are executed asynchronously from user requests and hence have no repository object for the current user
• repositoryManager: the object from where Repository's can be retrieved (using a specific login/password)
• variables: an object providing convenient access to process variables. This object supports the following methods:
• variables.getGlobalVariable(name)
• variables.setGlobalVariable(name, value)
• variables.deleteGlobalVariable(name)
• variables.getTaskVariable(name[, failOnNoTask]): the failOnNoTask argument is optional and true by default. Causes an exception to be thrown when this method is called outside the context of a task.
• variables.setTaskVariable(name, value)
• variables.deleteTaskVariable(name)
• executionContext, token, node, task, taskInstance: these are standard jBPM objects. The task and taskInstance objects are only available if applicable.

Assignment handler

Daisy provides a jBPM assignment handler which performs the assignment based on the value of the process variable containing a WfActorKey object. Here is an example:

<swimlane name="reviewer">
  <assignment class="org.outerj.daisy.workflow.jbpm_util.ActorKeyAssignmentHandler">
    <variableName>reviewer</variableName>
    <variableScope>global</variableScope>
  </assignment>
</swimlane>

The <variableName> element specifies the name of the variable, <variableScope> should be global or task.

A WfActorKey object can either point to a user or to one or more pools. Its fully qualified class name is:

org.outerj.daisy.workflow.WfActorKey

Task assignment notification mails

To send a notification mail when a task gets assigned to a user, you can associate a pre-made action with the task-assign event as illustrated below.

<task-node name="foo">
  <task name="fooTask" swimlane="initiator">
    <event type="task-assign">
      <action class="org.outerj.daisy.workflow.jbpm_util.NotifyTaskAssignAction"/>
    </event>
  </task>
  ...

The mail will be send to the email address of the user as configured in Daisy. If the user has no email address configured, no mail will be send (this will not give an error).

If the user to whom the task is assigned is the same as the current user (i.e. a user assigns a task to himself), no mail will be send. Similarly, when a task is unassigned, no mail will be send (as there's no-one to send the mail to).

The locale for sending the mail is currently taken from the email subscription manager, thus it is the same locale as used for sending notification mails in Daisy.

The task notification mail contains an URL to open the task. See here for information on how to configure this URL and how to customize the mail templates.