A ruleflow process is a flow chart where different types of nodes are linked using connections. The process itself exposes the following properties:
Id: The unique id of the process.
Name: The display name of the process.
Version: The version number of the process.
Package: The package (namespace) the process is defined in.
Variables: Variables can be defined to store data during the execution of your process. See section “Data” for details.
Swimlanes: Specify the actor responsible for the execution of human tasks. See chapter “Human Tasks” for details.
Exception Handlers: Specify the behaviour when a fault occurs in the process. See section “Exceptions” for details.
Connection Layout: Specify how the connections are visualized on the canvas using the connection layout property:
'Manual' always draws your connections as lines going straight from their start to end point (with the possibility to use intermediate break points).
'Shortest path' is similar, but it tries to go around any obstacles it might encounter between the start and end point, to avoid lines crossing nodes.
'Manhattan' draws connections by only using horizontal and vertical lines.
A RuleFlow process supports different types of nodes:
Start: The start of the ruleflow. A ruleflow should have exactly one start node, which cannot have incoming connections and should have one outgoing connection. Whenever a RuleFlow process is started, execution will start at this node and automatically continue to the first node linked to this start node, and so on. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Triggers: A Start node can also specify additional triggers that can be used to automatically start the process. Examples are a "constraint" trigger that automatically starts the process if a given rule or constraint is satisfied, or an "event" trigger that automatically starts the process if a specific event is signalled.
End: The end of the ruleflow. A ruleflow should have one or more End nodes. The End node should have one incoming connection and cannot have outgoing connections. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Terminate: An End node can be terminating for the entire process (default) or just for the path. If the process is terminated, all nodes that are still active (on parallel paths) in this ruleflow are cancelled. Non-terminating End nodes are simply ends for some path, while other parallel paths still continue.
RuleFlowGroup: Represents a set of rules that need to be evaluated. The rules are evaluated when the node is reached. A RuleFlowGroup node should have one incoming connection and one outgoing connection. Rules can become part of a specific ruleflow group using the <kw>ruleflow-group</kw> attribute in the header. When a RuleFlowGroup node is reached in the ruleflow, the engine will start executing rules that are part of the corresponding ruleflow-group (if any). Execution will automatically continue to the next node if there are no more active rules in this ruleflow group. This means that, during the execution of a ruleflow group, it is possible that new activations belonging to the currently active ruleflow group are added to the Agenda due to changes made to the facts by the other rules. Note that the ruleflow will immediately continue with the next node if it encounters a ruleflow group where there are no active rules at that time. If the ruleflow group was already active, the ruleflow group will remain active and exeution will only continue if all active rules of the ruleflow group has been completed. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
RuleFlowGroup: The name of the ruleflow group that represents the set of rules of this RuleFlowGroup node.
Timers: Timers that are linked to this node. See section “Timers” for details.
Split: Allows you to create branches in your ruleflow. A Split node should have one incoming connection and two or more outgoing connections. There are three types of Split nodes currently supported:
AND means that the control flow will continue in all outgoing connections simultaneously.
XOR means that exactly one of the outgoing connections will be chosen. The decision is made by evaluating the constraints that are linked to each of the outgoing connections. Constraints are specified using the same syntax as the left-hand side of a rule. The constraint with the lowest priority number that evaluates to true is selected. Note that you should always make sure that at least one of the outgoing connections will evaluate to true at runtime (the ruleflow will throw an exception at runtime if it cannot find at least one outgoing connection). For example, you could use a connection which is always true (default) with a high priority number to specify what should happen if none of the other connections can be taken.
OR means that all outgoing connections whose condition evaluates to true are selected. Conditions are similar to the XOR split, except that no priorities are taken into account. Note that you should make sure that at least one of the outgoing connections will evaluate to true at runtime because the ruleflow will throw an exception at runtime if it cannot determine an outgoing connection.
It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Type: The type of the split node, i.e., AND, XOR or OR (see above).
Constraints: The constraints linked to each of the outgoing connections (in case of an (X)OR split).
Join: Allows you to synchronize multiple branches. A join node should have two or more incoming connections and one outgoing connection. There are four types of splits currently supported:
AND means that is will wait until all incoming branches are completed before continuing.
XOR means that it continues as soon as one of its incoming branches has been completed. If it is triggered from more than one incoming connection, it will trigger the next node for each of those triggers.
Discriminator means that it continues if one of its incoming branches has been completed. Completions of other incoming branches are registered until all connections have completed. At that point, the node will be reset, so that it can trigger again when one of its incoming branches has been completed once more.
n-of-m means that it continues if n of its m incoming branches have been completed. The variable n could either be hardcoded to a fixed value, or refer to a process variable that will contain the number of incoming branches to wait for.
It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Type: The type of the Join node, i.e. AND, XOR or Discriminator (see above).
n: The number of incoming connections to wait for (in case of a n-of-m join).
EventWait (or Milestone): Represents a wait state. An EventWait should have one incoming connection and one outgoing connection. It specifies a constraint which defines how long the process should wait in this state before continuing. For example, a constraint in an order entry application might specify that the process should wait until no more errors are found in the given order. Constraints are specified using the same syntax as the left-hand side of a rule. When a Wait node is reached in the ruleflow, the engine will check the associated constraint. If the constraint evaluates to true directly, the flow will continue imediately. Otherwise, the flow will continue if the constraint is satisfied later on, for example when a fact is inserted, updated or removed from the working memory. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Constraint: Defines when the process can leave this state and continue.
SubFlow: represents the invocation of another process from within this process. A sub-process node should have one incoming connection and one outgoing connection. When a SubFlow node is reached in the ruleflow, the engine will start the process with the given id. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
ProcessId: The id of the process that should be executed.
Wait for completion: If this property is true, the SubFlow node will only continue if that SubFlow process has terminated its execution (completed or aborted); otherwise it will continue immediately after starting the subprocess.
Independent: If this property is true, the subprocess is started as an independent process, which means that the SubFlow process will not be terminated if this process reaches an end node; otherwise the active sub-process will be cancelled on termination (or abortion) of the process.
On-entry and on-exit actions: Actions that are executed upon entry or exit of this node, respectively.
Parameter in/out mapping: A SubFlow node can also define in- and out-mappings for variables. The value of variables in this process with variable names given in the "in" mapping will be used as parameters (with the associated parameter name) when starting the process. The value of the variables in the subprocess with the given variable name in the "out" mappings will be copied to the variables of this process when the subprocess has been completed. Note that you can use "out" mappings only when "Wait for completion" is set to true.
Timers: Timers that are linked to this node. See section “Timers” for details.
Action: represents an action that
should be executed in this ruleflow. An Action node should have one incoming
connection and one outgoing connection. The associated action specifies what
should be executed, the dialect used for coding the action (i.e., Java or MVEL),
and the actual action code. This code can access any globals, the predefined
variable drools
referring to a KnowledgeHelper
object
(which can, for example,
be used to retrieve the Working Memory by calling
drools.getWorkingMemory()
), and the variable context
that references the ProcessContext
object (which can,
for example, be used to access the current ProcessInstance
or
NodeInstance
, and to get and set variables). When an Action node
is reached in the ruleflow, it will execute the action and then continue with the
next node. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Action: The action associated with this action node.
Timer: represents a timer that can trigger one or multiple times after a given period of time. A Timer node should have one incoming connection and one outgoing connection. The timer delay specifies how long (in milliseconds) the timer should wait before triggering the first time. The timer period specifies the time between two subsequent triggers. A period of 0 means that the timer should only be triggered once. When a Timer node is reached in the ruleflow, it will start the associated timer. The timer is cancelled if the timer node is cancelled (e.g., by completing or aborting the process). Consult the section “Timers” for more information. - The Timer node contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Timer delay: The delay (in milliseconds) that the node should wait before triggering the first time.
Timer period: The period (in milliseconds) between two subsequent triggers. If the period is 0, the timer should only be triggered once.
Fault: A Fault node can be used to signal an exceptional condition in the process. It should have one incoming connection and no outgoing connections. When a Fault node is reached in the ruleflow, it will throw a fault with the given name. The process will search for an appropriate exception handler that is capable of handling this kind of fault. If no fault handler is found, the process instance will be aborted. A Fault node contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
FaultName: The name of the fault. This name is used to search for appriopriate exception handlers that is capable of handling this kind of fault.
FaultVariable: The name of the variable that contains the data associated with this fault. This data is also passed on to the exception handler (if one is found).
Event: An Event node can be used to respond to internal or external events during the execution of the process. An Event node should have no incoming connections and one outgoing connection. It specifies the type of event that is expected. Whenever that type of event is detected, the node connected to this Event node will be triggered. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
EventType: The type of event that is expected.
VariableName: The name of the variable that will contain the data associated with this event (if any) when this event occurs.
Scope: An event could be used to listen
to internal events only, i.e., events that are signalled to this
process instance directly, using
processInstance.signalEvent(String type, Object data)
.
When an Event node is defined as external, it will also be listening
to external events that are signalled to the process engine directly,
using workingMemory.signalEvent(String type, Object event)
.
Human Task: Processes can also involve tasks that need to be executed by human actors. A Human Task node represents an atomic task to be executed by a human actor. It should have one incoming connection and one outgoing connection. Human Task nodes can be used in combination with Swimlanes to assign multiple human tasks to similar actors. Refer to chapter “Human Tasks” for more details. A Human Task node is actually nothing more than a specific type of work item node (of type "Human Task"). A Human Task node contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
TaskName: The name of the human task.
Priority: An integer indicating the priority of the human task.
Comment: A comment associated with the human task.
ActorId: The actor id that is responsible for executing the human task. A list of actor id's can be specified using a comma (',') as separator.
Skippable: Specifies whether the human task can be skipped, i.e., whether the actor may decide not to execute the task.
Content: The data associated with this task.
Swimlane: The swimlane this human task node is part of. Swimlanes make it easy to assign multiple human tasks to the same actor. See the human tasks chapter for more detail on how to use swimlanes.
Wait for completion: If this property is true, the human task node will only continue if the human task has been terminated (i.e., by completing or reaching any other terminal state); otherwise it will continue immediately after creating the human task.
On.entry and on-exit actions: Actions that are executed upon entry and exit of this node, respectively.
Parameter mapping: Allows copying the value of process variables to parameters of the human task. Upon creation of the human tasks, the values will be copied.
Result mapping: Allows copying the value of result parameters of the human task to a process variable. Upon completion of the human task, the values will be copied. Note that you can use result mappings only when "Wait for completion" is set to true. A human task has a result variable "Result" that contains the data returned by the human actor. The variable "ActorId" contains the id of the actor that actually executed the task.
Timers: Timers that are linked to this node. Consult the section “Timers” for details.
Composite: A Composite node is a node that can contain other nodes so that it acts as a node container. This allows not only the embedding of a part of the flow within such a Composite node, but also the definition of additional variables and exception handlers that are accessible for all nodes inside this container. A Composite node should have one incoming connection and one outgoing connection. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
StartNodeId: The id of the node (within this node container) that should be triggered when this node is triggered.
EndNodeId: The id of the node (within this node container) that represents the end of the flow contained in this node. When this node is completed, the composite node will also be completed and trigger its outgoing connection. All other executing nodes within this composite node will be cancelled.
Variables: Additional variables can be defined to store data during the execution of this node. See section “Data” for details.
Exception Handlers: Specify the behavior when a fault occurs in this node container. See section “Exceptions” for details.
ForEach: A ForEach node is a special kind of composite node that allows you to execute the contained flow multiple times, once for each element in a collection. A ForEach node should have one incoming connection and one outgoing connection. A ForEach node awaits the completion of the embedded flow for each of the collection''s elements before continuing. It contains the following properties:
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
StartNodeId: The id of the node (within this node container) that should be triggered for each of the elements in a collection.
EndNodeId: The id of the node (within this node container) that represents the end of the flow contained in this node. When this node is completed, the execution of the ForEach node will also be completed for the current collection element. The outgoing connection is triggered if the collection is exhausted. All other executing nodes within this composite node will be cancelled.
CollectionExpression: The name of a
variable that represents the collection of elements that should
be iterated over. The collection variable should be of type
java.util.Collection
.
VariableName: The name of the variable to contain the current element from the collection. This gives nodes within the composite node access to the selected element.
WorkItem: Represents an (abstract) unit of work that should be executed in this process. All work that is executed outside the process engine should be represented (in a declarative way) using a WorkItem node. Different types of work items are predefined, e.g., sending an email, logging a message, etc. Users can define domain-specific work items, using a unique name and by defining the parameters (input) and results (output) that are associated with this type of work. Refer to the chapter “Domain-specific processes” for a detailed explanation and illustrative examples of how to define and use work items in your processes. When a WorkItem node is reached in the process, the associated work item is executed. A WorkItem node should have one incoming connection and one outgoing connection.
Id: The id of the node (which is unique within one node container).
Name: The display name of the node.
Wait for completion: If the property "Wait for completion" is true, the WorkItem node will only continue if the created work item has terminated (completed or aborted) its execution; otherwise it will continue immediately after starting the work item.
Parameter mapping: Allows copying the value of process variables to parameters of the work item. Upon creation of the work item, the values will be copied.
Result mapping: Allows copying the value
of result parameters of the work item to a process variable. Each
type of work can define result parameters that will (potentially)
be returned after the work item has been completed. A result
mapping can be used to copy the value of the given result parameter
to the given variable in this process. For example, the "FileFinder"
work item returns a list of files that match the given search
criteria within the result parameter Files
. This list
of files can then be bound to a process variable for use within the
process. Upon completion of the work item, the values will be copied.
Note that you can use result mappings only when "Wait for completion"
is set to true.
On-entry and on-exit actions: Actions that are executed upon entry or exit of this node, respectively.
Timers: Timers that are linked to this node. See the section “Timers” for details.
Additional parameters: Each type of work
item can define additional parameters that are relevant for that
type of work. For example, the "Email" work item defines additional
parameters such as From
, To
, Subject
and Body
. The user can either provide values for these
parameters directly, or define a
parameter mapping that will copy the value of the given variable
in this process to the given parameter; if both are specified, the
mapping will have precedence. Parameters of type String
can use
#{expression}
to embed a value in the
string. The value will be retrieved when creating the work item, and the
substitution expression will be replaced by the result of calling
toString()
on the variable. The expression could
simply be the name of a variable (in which case it resolves
to the value of the variable), but more advanced MVEL expressions
are possible as well, e.g., #{person.name.firstname}
.