Actions are pieces of java code that are executed upon events in the process execution. The graph is an important instrument in the communication about software requirements. But the graph is just one view (projection) of the software being produced. It hides many technical details. Actions are a mechanism to add technical details outside of the graphical representation. Once the graph is put in place, it can be decorated with actions. This means that java code can be associated with the graph without changing the structure of the graph. The main event types are entering a node, leaving a node and taking a transition.
Note the difference between an action that is placed in an event versus an action that is placed in a node. Actions that are put in an event are executed when the event fires. Actions on events have no way to influence the flow of control of the process. It is similar to the observer pattern. On the other hand, an action that is put on a node has the responsibility of propagating the execution.
Let's look at an example of an action on an event. Suppose we want to do a database update on a given transition. The database update is technically vital but it is not important to the business analyst.
public class RemoveEmployeeUpdate implements ActionHandler {
public void execute(ExecutionContext ctx) throws Exception {
// get the fired employee from the process variables.
String firedEmployee = (String) ctx.getContextInstance().getVariable("fired employee");
// by taking the same database connection as used for the jbpm updates, we
// reuse the jbpm transaction for our database update.
Connection connection = ctx.getProcessInstance().getJbpmSession().getSession().getConnection();
Statement statement = connection.createStatement();
statement.execute("DELETE FROM EMPLOYEE WHERE ...");
statement.execute();
statement.close();
}
}<process-definition name="yearly evaluation">
...
<state name="fire employee">
<transition to="collect badge">
<action class="com.nomercy.hr.RemoveEmployeeUpdate" />
</transition>
</state>
<state name="collect badge">
...
</process-definition>For more information about adding configurations to your custom actions and how
to specify the configuration in the processdefinition.xml,
see the section called “Configuration of delegations”
Actions can be given a name. Named actions can be referenced from other locations where actions can be specified. Named actions can also be put as child elements in the process definition.
This feature is interesting if you want to limit duplication of action configurations (e.g. when the action has complicated configurations). Another use case is execution or scheduling of runtime actions.
Events specify moments in the execution of the process. The jBPM engine
will fire events during graph execution. This occurs when jbpm calculats the
next state (read: processing a signal). An event is always relative to an element
in the process definition like e.g. the process definition, a node or a transition.
Most process elements can fire different types of events. A node for example can
fire a node-enter event and a node-leave
event. Events are the hooks for actions. Each event has a list of actions.
When the jBPM engine fires an event, the list of actions is executed.
Superstates create a parent-child relation in the elements of a process definition. Nodes and transitions contained in a superstate have that superstate as a parent. Top level elements have the process definition as a parent. The process definition does not have a parent. When an event is fired, the event will be propagated up the parent hierarchy. This allows e.g. to capture all transition events in a process and associate actions with these events in a centralized location.
A script is an action that executes a beanshell script. For more information about beanshell, see the beanshell website. By default, all process variables are available as script-variables and no script-variables will be written to the process variables. Also the following script-variables will be available :
- executionContext
- token
- node
- task
- taskInstance
<process-definition>
<event type="node-enter">
<script>
System.out.println("this script is entering node "+node);
</script>
</event>
...
</process-definition>To customize the default behaviour of loading and storing variables into the script, the
variable element can be used as a sub-element of script. In that case,
the script expression also has to be put in a subelement of script: expression.
<process-definition>
<event type="process-end">
<script>
<expression>
a = b + c;
</expression>
<variable name='XXX' access='write' mapped-name='a' />
<variable name='YYY' access='read' mapped-name='b' />
<variable name='ZZZ' access='read' mapped-name='c' />
</script>
</event>
...
</process-definition>Before the script starts, the process variables YYY and
ZZZ will be made available to the script as script-variables
b and c respectively. After the script is
finished, the value of script-variable a is stored into the
process variable XXX.
If the access attribute of variable contains
'read', the
process variable will be loaded as a script-variable before script evaluation. If the
access attribute contains 'write', the script-variable
will be stored as a process variable after evaluation.
The attribute mapped-name can make the process variable available under another
name in the script. This can be handy when your process variable names contain spaces or other
invalid script-literal-characters.
Note that it's possible to fire your own custom events at will during the
execution of a process. Events are uniquely defined by the combination of a graph
element (nodes, transitions, process definitions and superstates are graph elements)
and an event-type (java.lang.String). jBPM defines a set of events that are fired for
nodes, transitions and other graph elements. But as a user, you are free to fire your
own events. In actions, in your own custom node implementations, or even outside the execution
of a process instance, you can call the GraphElement.fireEvent(String eventType,
ExecutionContext executionContext);. The names of the event types can
be chosen freely.