[jboss-svn-commits] JBL Code SVN: r23506 - in labs/jbossrules/trunk/drools-docs/drools-docs-flow/en: Chapter-Eclipse and 3 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sat Oct 18 11:39:54 EDT 2008
Author: KrisVerlaenen
Date: 2008-10-18 11:39:54 -0400 (Sat, 18 Oct 2008)
New Revision: 23506
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/BPMN.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/Chapter-Eclipse.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/RuleFlow.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/preferences.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/EventProcess.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/FaultProcess.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/NewRF.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-HumanTasks/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-HumanTasks/Chapter-HumanTasks.xml
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/Chapter-RuleFlow.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/ruleflow_nodes.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-GettingStarted/Chapter-GettingStarted.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/master.xml
Log:
- updated drools-flow docs
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/BPMN.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/BPMN.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/Chapter-Eclipse.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/Chapter-Eclipse.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/Chapter-Eclipse.xml 2008-10-18 15:39:54 UTC (rev 23506)
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+
+ <title>Drools Eclipse IDE features</title>
+
+ <para>The Drools plugin for the Eclipse IDE provides a few additional features that
+ might be interesting for developers.</para>
+
+ <section>
+ <title>Process skins</title>
+
+ <para>We have introduced the concept of a (process) skin, which controls how the
+ different nodes inside a process are visualized. This allows you to change the
+ visualization of the different node types the way you like them (by implementing
+ your own SkinProvider).</para>
+
+ <para>BPMN is a popular language used by business users for modeling business
+ processes. BPMN defines terminology, different types of nodes, how these should
+ be visualized, etc. People who are familiar with BPMN might find it easier to
+ implement an executable process (possibly based on a BPMN process diagram) using
+ a similar visualization. We have therefore created a BPMN skin that maps the Drools
+ Flow concepts to the equivalent BPMN visualization.</para>
+
+ <para>For example, the following figure shows a process using some of the different
+ types of nodes in the RuleFlow language using the default skin ...</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="RuleFlow.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Simply by switching the preferred process skin in the Drools preferences ...</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="preferences.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>and then reopening the editor shows the same process using the BPMN skin ...</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="BPMN.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ </section>
+
+</chapter>
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/RuleFlow.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/RuleFlow.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/preferences.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Eclipse/preferences.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/Chapter-RuleFlow.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/Chapter-RuleFlow.xml 2008-10-18 08:03:41 UTC (rev 23505)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/Chapter-RuleFlow.xml 2008-10-18 15:39:54 UTC (rev 23506)
@@ -10,8 +10,658 @@
<imagedata align="center" fileref="RuleFlow.png" format="PNG" role="" />
</imageobject>
</mediaobject>
- </figure>
+ </figure>
+
+ <para>A RuleFlow is a process that describes the order in which a series of steps need to
+ be executed, using a flow chart. A process consists of a collection of nodes that are
+ linked to each other using connections. Each of the nodes represents one step in the
+ overall process while the connections specify how to transition from one node to the other.
+ A large selection of predefined node types have been defined. This chapter describes how
+ to define such processes and use them in your application.</para>
+ <section>
+ <title>Creating a RuleFlow process</title>
+
+ <para>Processes can be created by using one of the following three methods:
+ <orderedlist>
+ <listitem>Using the graphical RuleFlow editor in the Drools plug-in for Eclipse</listitem>
+ <listitem>As an XML file, according to the XML process format as defined in the
+ 'drools-processes' XML Schema Definition.</listitem>
+ <listitem>By directly creating a process using the Process API.</listitem>
+ </orderedlist>
+ </para>
+
+ <section>
+ <title>Using the graphical RuleFlow editor</title>
+
+ <para>The graphical RuleFlow editor is a editor that allows you to create a process
+ by dragging and dropping different nodes on a canvas and editing the properties of these
+ nodes. The graphical RuleFlow editor is part of the Drools plug-in for Eclipse. Once
+ you have set up a Drools project (check the IDE chapter if you do not know how to do this),
+ you can start adding processes. When in a project, launch the 'New' wizard (use "Ctrl+N"
+ or by right-clicking the directory you would like to put your ruleflow in and selecting
+ "New ... -> Other ...". Choose the section on "Drools" and then pick "RuleFlow file".
+ This will create a new .rf file.</para>
+
+ <figure>
+ <title>Creating a new RuleFlow file</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="RFNewWizard.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Next you will see the graphical ruleflow editor. Now would be a good time to
+ switch to the "Drools Perspective" (if you haven't done so already) - this will tweak the UI so
+ it is optimal for rules. Then ensure that you can see the "Properties" view down the bottom of
+ the Eclipse window, as it will be necessary to fill in the different properties of the elements
+ in your process. If you cannot see the properties view, open it using the menu Window ->
+ Show View -> Other ..., and under the General folder select the properties view.</para>
+
+ <figure>
+ <title>New RuleFlow process</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="NewRF.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The RuleFlow editor consists of a palette, a canvas and an outline view. To add
+ new elements to the canvas, select the element you would like to create in the palette
+ and then add them to the canvas by clicking on the preferred location. For example,
+ click on the RuleFlowGroup icon in the Component Pallette of the GUI
+ - you can then draw a few rule flow groups. Clicking on an element in your ruleflow
+ allows you to set the properties of that element.You can link the nodes together (as
+ long as it is allowed by the different types of nodes) by using "Connection Creation"
+ from the component palette.</para>
+
+ <para>You can keep adding nodes and connections to your process until it represents the
+ business logic that you want to specify. You'll probably need to check the process for
+ any missing information (by pressing the green "check" icon in the IDE menu bar) before
+ trying to use it in your application.</para>
+
+ </section>
+
+ <section>
+ <title>Defining processes using XML</title>
+
+ <para>It is also possible to specify processes using the underlying XML directly. The
+ syntax of these XML processes is defined using an XML Schema Definition. For example,
+ the following XML fragment shows a simple process that contains a sequence of
+ a start node, an action node that prints "Hello World" to the console, and an end node.</para>
+
+<programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+<process xmlns="http://drools.org/drools-4.0/process"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
+ xs:schemaLocation="http://drools.org/drools-4.0/process drools-processes-4.0.xsd"
+ type="RuleFlow" name="ruleflow" id="com.sample.ruleflow" package-name="com.sample" >
+
+ <header>
+ </header>
+
+ <nodes>
+ <start id="1" name="Start" x="16" y="16" />
+ <actionNode id="2" name="Hello" x="128" y="16" >
+ <action type="expression" dialect="mvel" >System.out.println("Hello World");</action>
+ </actionNode>
+ <end id="3" name="End" x="240" y="16" />
+ </nodes>
+
+ <connections>
+ <connection from="1" to="2" />
+ <connection from="2" to="3" />
+ </connections>
+
+</process>
+</programlisting>
+
+ <para>The process XML file should consist of exactly one <process> element. This element
+ contains parameters related to the process (the type, name, id and package name of the process),
+ and consists of three main subsections: a <header> (where process-level information like variables,
+ globals, imports and swimlanes can be defined), a <nodes> section that defines each of the nodes in
+ the process (there is a specific element for each of the different node types that defines the
+ various parameters and possibly sub-elements for that node type), and a <connections> section that
+ contains the connections between all the nodes in the process.</para>
+
+ </section>
+
+ <section>
+ <title>Defining processes using the Process API</title>
+
+ <para>While it is recommended to define processes using the graphical editor or the underlying XML (to
+ shield yourself from internal APIs), it is also possible to define a process using the Process API directly.
+ The most important process elements are defined in the org.drools.workflow.core and the
+ org.drools.workflow.core.node packages.Note that creating a process using this API can be rather complex
+ and error-prone, and should only be used if the above mentioned methods are not sufficient (for example
+ when automatically generating processes from input that is not XML-based). You can however use the process
+ validator (org.drools.ruleflow.core.validation.RuleFlowProcessValidator) to validate processes that were
+ manually created using the API.</para>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Using a process in your application</title>
+
+ <para>There are two things you need to do to be able to execute processes from
+ within your application: (1) you need to create a rulebase that contain
+ the definition of the process; and (2) you need to start the process by creating
+ a session to communicate with the process engine and start the process.</para>
+
+ <orderedlist>
+
+ <listitem><para><emphasis>Creating a rulebase</emphasis>: Once you
+ have a valid process, you can add a process to a package (just like adding a rule):
+ <programlisting>
+PackageBuilder builder = new PackageBuilder();
+Reader processReader = ... (process reader, select your *.rf file here)
+builder.addProcessFromXml(processReader);</programlisting>
+ Alternatively, you can upload the .rf file to Guvnor (as a
+ process asset) and it will automatically be included in packages that are
+ deployed from it.</para>
+ <para>Next you need to create a rulebase that contains all the necessary rules
+ and processes, like this:
+ <programlisting>
+RuleBase ruleBase = RuleBaseFactory.newRuleBase();
+ruleBase.addPackage(builder.getPackage());</programlisting>
+ </para></listitem>
+
+ <listitem><para><emphasis>Starting a process</emphasis>: Processes are only executed
+ if you explicitly state that they should be executed. This is because you could
+ potentially define a lot of processes in your rulebase and the engine has no way
+ to know when you would like to start each of these. To activate a particular process,
+ you will need to start the process by calling the startProcess method on your session.
+ For example:
+ <programlisting>StatefulSession session = ruleBase.newStatefulSession();
+session.startProcess("com.sample.MyProcess");</programlisting>
+ The parameter of the startProcess method represents the id of the process that needs to
+ be started (the process id needs to be specified as a property of the process, which are
+ shown in the properties view when you click the background canvas of your process).
+ If your process also requires the execution of rules during the execution of the process,
+ you also need to call the session.fireAllRules() method. Thats it !</para>
+ <para>You can also specify additional parameters that are used to pass on additional data
+ to the process, using the startProcess(String processId, Map parameters)
+ method, that takes an additional set of parameters as name-value pairs.
+ </para></listitem>
+
+ </orderedlist>
+
+ <para>You can also start a process from within a rule consequence using
+ <programlisting>drools.getWorkingMemory().startProcess("...");</programlisting>
+ </para>
+ </section>
+
+ <section>
+ <title>Detailed explanation of the different node types</title>
+
+ <para>A ruleflow process is a flow chart where different types of nodes are linked using connections. The process itself exposes the following properties:
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The unique id of the process.</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the process.</para></listitem>
+ <listitem><para><emphasis>Version</emphasis>: The version number of the process.</para></listitem>
+ <listitem><para><emphasis>Package</emphasis>: The package (namespace) the process is defined in.</para></listitem>
+ <listitem><para><emphasis>Variables</emphasis>: Variables can be defined to store data during the execution of your process (see the 'data' section for more details).</para></listitem>
+ <listitem><para><emphasis>Swimlanes</emphasis>: Specify the actor that is responsible for the execution of human tasks (see the 'human tasks' section for more details).</para></listitem>
+ <listitem><para><emphasis>Exception Handlers</emphasis>: Specify the behaviour when a fault occurs in the process (see the 'exceptions' section for more details).</para></listitem>
+ <listitem><para><emphasis>Connection Layout</emphasis>: Specify how the connections are visualized on the canvas using the connection layout property:
+ <itemizedlist>
+ <listitem>
+ <para>'Manual' always draws your connections as lines going straight from their start to end point (with the possibility to use intermediate break points).</para>
+ </listitem>
+ <listitem>
+ <para>'Shortest path' is similar, but it tries to go around any obstacles is might encounter between the start and end point (to avoid lines crossing nodes).</para>
+ </listitem>
+ <listitem>
+ <para>'Manhatten' draws connections by only using horizontal and vertical lines.</para>
+ </listitem>
+ </itemizedlist></para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>A RuleFlow process supports different types of nodes:
+
+ <figure>
+ <title>The different types of ruleflow nodes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="ruleflow_nodes.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <orderedlist>
+
+ <!-- START -->
+ <listitem>
+ <para><emphasis role="strong">Start</emphasis>: The start of the ruleflow. A ruleflow should have exactly one start node. The start node cannot have incoming connections and should have one outgoing connection. Whenever ruleflow process is started, the ruleflow will start executing here, and will then automatically continue to the first node linked to this start node, etc. It contains the following properties:
+ </para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Triggers</emphasis>: 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 / contraint is satisfied, or an 'event' trigger that automatically starts the process if a specific event is signalled.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- END -->
+ <listitem>
+ <para><emphasis role="strong">End</emphasis>: 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:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Terminate</emphasis>: An end node can be terminating (default) or not. When a terminating end node is reached in the ruleflow, the ruleflow is terminated. If a ruleflow is terminated, all nodes that are still active in this ruleflow are cancelled first (which is possible if parallel paths are used). Non-terminating end nodes are simply end nodes in the process where the flow ends but other parallel paths still continue.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- RULESET -->
+ <listitem>
+ <para><emphasis role="strong">RuleFlowGroup</emphasis>: 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 "ruleflow-group" attribute in the header. When a RuleSet 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 point!
. 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:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>RuleFlowGroup</emphasis>: The name of the ruleflow-group that represents the set of rules of this RuleFlowGroup node.</para></listitem>
+ <listitem><para><emphasis>Timers</emphasis>: Timers that are linked to this node (see the 'timers' section for more details).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- SPLIT -->
+ <listitem>
+ <para><emphasis role="strong">Split</emphasis>: 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 splits currently supported:
+ <itemizedlist>
+ <listitem>
+ <para>AND means that the control flow will continue in all outgoing connections simultaneously (paralellism).
+ </para>
+ </listitem>
+ <listitem>
+ <para>XOR means that exactly one of the outgoing connections will be chosen (decision). Which connection is decided 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>OR means that all outgoing connections whose condition evaluates to true are selected. Conditions are similar to the XOR split, except that the priorities are not taken into account. Note that you should 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 an outgoing connection).
+ </para>
+ </listitem>
+ </itemizedlist>
+ It contains the following properties:
+ </para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Type</emphasis>: The type of the split node, t.e. AND, XOR or OR (see above).</para></listitem>
+ <listitem><para><emphasis>Constraints</emphasis>: The constraints linked to each of the outgoing connections (in case of an (X)OR split).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- JOIN -->
+ <listitem>
+ <para><emphasis role="strong">Join</emphasis>: Allows you to synchronize multiple branches. A join node should have two or more incoming connections and one outgoing connection. There are three types of splits currently supported:
+ <itemizedlist>
+ <listitem>
+ <para>AND means that is will wait until all incoming branches are completed before continuing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>XOR means that it continues if one of its incoming branches has been completed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Discriminator means that it continues if one of its incoming branches has been completed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ It contains the following properties:
+ </para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Type</emphasis>: The type of the join node, t.e. AND, XOR or Discriminator (see above).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- EVENT WAIT -->
+ <listitem>
+ <para><emphasis role="strong">Event wait (or milestone)</emphasis>: Represents a wait state. An event wait 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 in, updated or removed from the working memory. It contains the following properties:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Constraint</emphasis>: Defines when the process can leave this state and continue.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- SUBPROCESS -->
+ <listitem>
+ <para><emphasis role="strong">SubFlow</emphasis>: represents the invocation of another process from withing this process. A sub-process node should have one incoming connection and one outgoing connection. When a SubProcess node is reached in the ruleflow, the engine will start the process with the given id. It contains the following properties:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>ProcessId</emphasis>: The id of the process that should be executed.</para></listitem>
+ <listitem><para><emphasis>Wait for completion</emphasis>: 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 sub-process.</para></listitem>
+ <listitem><para><emphasis>Independent</emphasis>: If this property is true, the sub-process 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.</para></listitem>
+ <listitem><para><emphasis>On entry/exit actions</emphasis>: Actions that are executed upon entry / exit of this node.</para></listitem>
+ <listitem><para><emphasis>Parameter in/out mapping</emphasis>: A SubFlow node can also define in- and out-mappings for variables. The value of variables in this process with given variable name in the in-mappings will be used as parameters (with the associated parameter name) when starting the process. The value of the variables in the sub-process with the given variable name in the out-mappings will be copied to the variables of this process when the sub-process has been completed. Note that can only use out-mappings when "Wait for completion" is set to true.</para></listitem>
+ <listitem><para><emphasis>Timers</emphasis>: Timers that are linked to this node (see the 'timers' section for more details).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- ACTION -->
+ <listitem>
+ <para><emphasis role="strong">Action</emphasis>: 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. An action should specify which dialect is used to specify the action (e.g. Java or MVEL), and the actual action code. The action code can refer to any globals, the special 'drools' variable which implements KnowledgeHelper (can for example be used to access the working memory (drools.getWorkingMemory())) and the special 'context' variable which implements the ProcessContext (can for example be used to access the current ProcessInstance or NodeInstance and get/set variables). When an action node is reached in the ruleflow, it will execute the action and continue with the next node. It contains the following properties:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Action</emphasis>: The action associated with this action node.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- TIMER -->
+ <listitem>
+ <para><emphasis role="strong">Timer</emphasis>: 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 timerperiod specifies the time between two subsequenct 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 execute the associated timer. The timer is cancelled if the timer node is cancelled (e.g. by completing or aborting the process). It contains the following properties:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Timer delay</emphasis>: The delay (in milliseconds) that the node should wait before triggering the first time.</para></listitem>
+ <listitem><para><emphasis>Timer period</emphasis>: The period (in milliseconds) between two subsequent triggers. If the period is 0, the timer should only be triggered once.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- FAULT -->
+ <listitem>
+ <para><emphasis role="strong">Fault</emphasis>: A fault node can be used to signal an exceptional condition in the process. A fault node 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. It contains the following properties:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>FaultName</emphasis>: The name of the fault. This name is used to search for appriopriate exception handlers that is capable of handling this kind of fault.</para></listitem>
+ <listitem><para><emphasis>FaultVariable</emphasis>: 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).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- EVENT -->
+ <listitem>
+ <para><emphasis role="strong">Event</emphasis>: An event node can be used to respond to (internal/external) events during the execution of the process. An event node should have no incoming connections and one outgoing connection. An event node 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:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>EventType</emphasis>: The type of event that is expected.</para></listitem>
+ <listitem><para><emphasis>VariableName</emphasis>: The name of the variable that will contain the data associated with this event (if any) when this event occurs.</para></listitem>
+ <listitem><para><emphasis>Scope</emphasis>: 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).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- HUMAN TASK -->
+ <listitem>
+ <para><emphasis role="strong">Human Task</emphasis>: Processes can also involve tasks that need to executed by human actors. A task node represents an atomic task that needs to be executed by a human actor. A human task node 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 the similar actors. For more detail, check the 'human tasks' chapter. 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:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>TaskName</emphasis>: The name of the human task.</para></listitem>
+ <listitem><para><emphasis>Priority</emphasis>: An integer indicating the priority of the human task.</para></listitem>
+ <listitem><para><emphasis>Comment</emphasis>: A comment associated with the human task.</para></listitem>
+ <listitem><para><emphasis>ActorId</emphasis>: 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.</para></listitem>
+ <listitem><para><emphasis>Skippable</emphasis>: Specifies whether the human task can be skipped (i.e. the actor decides not to execute the human task).</para></listitem>
+ <listitem><para><emphasis>Wait for completion</emphasis>: If this property is true, the human task node will only continue if the human task has been terminated (i.e. completed or any other terminal state); otherwise it will continue immediately after creating the human task.</para></listitem>
+ <listitem><para><emphasis>On entry/exit actions</emphasis>: Actions that are executed upon entry / exit of this node.</para></listitem>
+ <listitem><para><emphasis>Parameter mapping</emphasis>: Allows copying the value of process variables to parameters of the human task. Upon creation of the human tasks, the values will be copied.</para></listitem>
+ <listitem><para><emphasis>Result mapping</emphasis>: 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 can only use result mappings when "Wait for completion" is set to true.</para></listitem>
+ <listitem><para><emphasis>Timers</emphasis>: Timers that are linked to this node (see the 'timers' section for more details).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- COMPOSITE -->
+ <listitem>
+ <para><emphasis role="strong">Composite</emphasis>: A composite node is a node that can contain other nodes (i.e. acts as a node container). It thus allows creating a part of the flow embedded inside a composite node. It also allows you to define 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:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>StartNodeId</emphasis>: The id of the node (inside this node container) that should be triggered when this node is triggered.</para></listitem>
+ <listitem><para><emphasis>EndNodeId</emphasis>: The id of the node (inside 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.</para></listitem>
+ <listitem><para><emphasis>Variables</emphasis>: Additional variables can be defined to store data during the execution of this node (see the 'data' section for more details).</para></listitem>
+ <listitem><para><emphasis>Exception Handlers</emphasis>: Specify the behaviour when a fault occurs in this node container (see the 'exceptions' section for more details).</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- FOR EACH -->
+ <listitem>
+ <para><emphasis role="strong">For Each</emphasis>: A for each 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 for each node should have one incoming connection and one outgoing connection. A for each node waits for completion of the embedded flow for each of its elements before continuing. It contains the following properties:</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>StartNodeId</emphasis>: The id of the node (inside this node container) that should be triggered for each of the elements in a collection.</para></listitem>
+ <listitem><para><emphasis>EndNodeId</emphasis>: The id of the node (inside this node container) that represents the end of the flow contained in this node. When this node is completed, the execution of the for each node will also be completed for that element. and trigger its outgoing connection. All other executing nodes within this composite node will be cancelled.</para></listitem>
+ <listitem><para><emphasis>CollectionExpression</emphasis>: 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.</para></listitem>
+ <listitem><para><emphasis>VariableName</emphasis>: The name of the variable that will contain the selected element from the collection. This can be used to gives nodes inside this composite node access to the selected element.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ <!-- WORK ITEMS -->
+ <listitem>
+ <para><emphasis role="strong">Work Item</emphasis>: 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 work item. Different types of work items are predefined, like for example sending an email, logging a message, etc. However, the user can define domain-specific work items (using a unique name and by defining the paramaters (input) and results (output) that are associated with this type of work). See the chapter about domain-specific processes for a detailed explanation and illustrative examples of how to define and use work items in your processes. When a work item node is reached in the process, the associated work item is executed. A work item node should have one incoming connection and one outgoing connection.</para>
+ <itemizedlist>
+ <listitem><para><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</para></listitem>
+ <listitem><para><emphasis>Name</emphasis>: The display name of the node.</para></listitem>
+ <listitem><para><emphasis>Wait for completion</emphasis>: If the property "Wait for completion" is true, the WorkItem node will only continue if the created work item has terminated its execution (completed or aborted); otherwise it will continue immediately after starting the work item.</para></listitem>
+ <listitem><para><emphasis>Parameter mapping</emphasis>: Allows copying the value of process variables to parameters of the work item. Upon creation of the work item, the values will be copied.</para></listitem>
+ <listitem><para><emphasis>Result mapping</emphasis>: 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 as a 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 can only use result mappings when "Wait for completion" is set to true.</para></listitem>
+ <listitem><para><emphasis>On entry/exit actions</emphasis>: Actions that are executed upon entry / exit of this node.</para></listitem>
+ <listitem><para><emphasis>Timers</emphasis>: Timers that are linked to this node (see the 'timers' section for more details).</para></listitem>
+ <listitem><para><emphasis>Additional parameters</emphasis>: 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 like 'From', 'To', 'Subject' and 'Body'. The user can either fill in 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 the #{variableName} to embed the value of a variable in the String. The value of the variable will be retrieved when creating the work item and the #{...} will be replaced by the toString() value of the variable.</para></listitem>
+ </itemizedlist>
+ </listitem>
+
+ </orderedlist>
+ </para>
+ </section>
+
+ <section>
+ <title>Data</title>
+
+ <para>While the flow graph focusses on specifying the control flow of the process, it is usually also
+ necessary to look at the process from a data perspective. During the execution of a process, data
+ can retrieved, stored, passed on and (re)used throughout the entire process.
+ </para>
+
+ <para>Runtime data can be stored during the execution of the process using variables. A variable is defined
+ by a name and a data type. This could be a basic data types (e.g. boolean, integer, String) or any kind of
+ Object. Variables can be defined inside a variable scope. The top-level scope is the variable scope of the
+ process itself. Sub-scopes can be defined using a composite node. Variables that are defined in a sub-scope
+ are only accessible for nodes within that scope.</para>
+
+ <para>Whenever a variable is accessed, the process will search for the appropriate variable scope that defines
+ the variable. Nesting of variable scopes is allowed: a node will always search for a variable in its
+ parent container. If the variable cannot be found, it will look in that one's parent container, etc. until the
+ process instance itself is reached. If the variable cannot be found, either null will be returned (in case of
+ a read) or an error message will be shown that the variable could not be found (in case of a write), after which
+ the process will continue without setting the paramater.</para>
+
+ <para>Variables can be used in various ways:
+ <itemizedlist>
+ <listitem>Process-level variables can be set when starting a process by providing a map of parameters when
+ invoking the startProcess method. These parameters will be set as variables on the process scope.</listitem>
+ <listitem>Actions can read/write variables through the process context using
+ <programlisting>Object value = context.getVariable(variableName);</programlisting> and
+ <programlisting>context.setVariable(variableName, value);</programlisting></listitem>
+ <listitem>Work items and sub-flows can pass the value of parameters to the outside world by mapping the variable to one
+ of the work item parameters (either using a parameter mapping or by using #{variableName} directly inside
+ a String parameter. The results of a work item can also be copied to a variable using a result mapping.</listitem>
+ <listitem>Sub-processes can also mapWork items can pass the value of parameters to the outside world by mapping the variable to one
+ of the work item parameters (either using a parameter mapping or by using #{variableName} directly inside
+ a String parameter. The results of a work item can also be copied to a variable using a result mapping.</listitem>
+ </itemizedlist>
+manipulating data: parameters when starting process, parameter mapping (sub-flow, work item, etc.) actions (context.get/setParameter()), various nodes do automatic mapping of data to a variable (event node, exception handler)</para>
+
+ <para>globals, data in working memory, etc</para>
+ </section>
+
+ <section>
+ <title>Constraints</title>
+
+ <para>Two types of constraints:
+ <itemizedlist>
+ <listitem>rule: Rule constraints are equals to rule conditions and refer to data in the working memory.</listitem>
+ <listitem>code: Code constraints are expressions that return a boolean value. They have access to the context variable. MVEL code constraints also have direct access to the variables.</listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Both rule and code constraints have access to globals that are defined for
+ the process and can reuse imports at the process level.</para>
+ </section>
+
+ <section>
+ <title>Actions</title>
+
+ <para>Actions can be used in different ways:
+ <itemizedlist>
+ <listitem>Action node: </listitem>
+ <listitem>On entry/exit actions: </listitem>
+ <listitem>Actions that specify the behaviour of exception handlers</listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Actions have access to globals that are defined for
+ the process and the context variable. The context variable can be used for
+ <itemizedlist>
+ <listitem>Getting the current node instance (if applicable). The node instance could be queried for data (name, type). You can also cancel the current node instance.</listitem>
+ <listitem>Getting the current process instance. This process instance could be queried for data (name, id, processId, etc.), abort process instance.</listitem>
+ <listitem>Signalling events: internal or external</listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section>
+ <title>Events</title>
+
+ <figure>
+ <title>A sample process using events</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="EventProcess.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>During the execution of a process, the process engine makes sure that all the relevant
+ tasks are executed according to the process plan, by requesting the execution of work items
+ and waiting for the results. However, it is also possible that the process should respond to
+ events that were not directly requested by the process engine. Explicitly representing these
+ events in a process allows the process author to specify how the process should react whenever
+ such events occur.</para>
+
+ <para>Events have a type and possibly data associated with the event. Users are free to define
+ their own types of events and the data that is associated with this event.
+ </para>
+
+ <para>A process can specify how to respond to events by using event nodes. An event node needs
+ to specify the type of event the node is interested in. It can also define a variable name, which
+ defines the variable that the data that is associated with the event will be copied to. This allows
+ subsequent nodes in the process to access the event data and take appropriate action based on this
+ data.</para>
+
+ <para>An event can be signalled to a running instance of a process in a number of ways:
+ <itemizedlist>
+ <listitem>Internal event: Any action inside a process (e.g. the action of an action node,
+ or on-entry or on-exit actions of nodes) can signal the occurence of an internal event to
+ the surrounding process instance using
+ <programlisting>context.getProcessInstance().signalEvent(type, eventData);</programlisting></listitem>
+ <listitem>External event: A process instance can be notified of an event from outside using
+ <programlisting>processInstance.signalEvent(type, eventData);</programlisting></listitem>
+ <listitem>External event using event correlation: Instead of notifying a process instance directly,
+ it is also possible to have the engine automatically determine which process instances might be interested
+ in an event using event correlation (based on the event type). All process instances that have specified
+ they are interested in receiving external events of that type (e.g. by having an event node that is
+ listening to external events of that type) will be notified. You can signal such
+ an event to the process engine using
+ <programlisting>workingMemory.signalEvent(type, eventData);</programlisting></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Events could also be used to start a process. Whenever a start node defines an event trigger of a
+ specific type, a new process instance will be started every time that type of event is signalled to the
+ process engine.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Exceptions</title>
+
+ <figure>
+ <title>A sample process using exception handlers</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="FaultProcess.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Whenever an exceptional condition occurs during the execution of a process, a fault could be raised
+ to signal the occurrence of this exception. The process will then search for an appropriate exception handler
+ that is capable of handling such a fault.</para>
+
+ <para>Similar to events, faults also have a type and possibly data associated with the fault. Users are free to define
+ their own types of faults and the data that is associated with this fault.</para>
+
+ <para>Faults can be created using a fault node: A fault node generates a fault of the given type (i.e. the fault name).
+ If the fault node specifies a fault variable, the value of the given variable will be associated with the fault.</para>
+
+ <para>Whenever a fault is created, the process will search for an appropriate exception handler that is capable
+ of handling the given type of fault. Processes and composite nodes both can define exception handlers for handling
+ faults. Nesting of exception handlers is allowed: a node will always search for an appropriate exception handler in its
+ parent container. If none is found, it will look in that one's parent container, etc. until the process instance
+ itself is reached. If no exception handler can be found, the process instance will be aborted, resulting in the cancellation
+ of all nodes inside the process.</para>
+
+ <para>Exception handlers can also specify a fault variable. The data associated with the fault (if any) will be copied
+ to this variable if the exception handler is selected to handle the fault. This allows subsequent actions / nodes in the
+ process to access the fault data and take appropriate action based on this data.</para>
+
+ <para>Exception handlers need to define an action that specifies how to respond to the given fault. In most cases, the
+ behaviour that is needed to react to the given fault cannot be handled in one action. It is therefore recommended
+ to have the exception handler signal an event of a specific type (in this case "Fault") using
+ <programlisting>context.getProcessInstance().signalEvent("FaultType", context.getVariable("FaultVariable");</programlisting>
+ </para>
+
+ </section>
+
+ <section>
+ <title>Timers</title>
+
+ <para>Timers can be used to wait for a predefined amount of time, before
+ triggering. They could be used to specify timeout behaviour, to trigger
+ certain logic after a certain period or repeat it at regular intervals.</para>
+
+ <para>A timer needs to specify a delay and a period. The delay specifies the
+ amount of time (in milliseconds) to wait after activation before triggering the
+ timer the first time. The period defines the time between subsequent activations.
+ If the period is 0, the timer will only be triggered once.</para>
+
+ <para>The timer service is responsible for making sure that timers get triggered
+ at the appropriate times. Timers can also be cancelled, meaning that the timer
+ will no longer be triggered.</para>
+
+ <para>Timers can be used in two ways inside a process:
+ <itemizedlist>
+ <listitem>TimerNode: A timer node is a node that can be added to the process flow.
+ When the timer node is triggered, the associated timer is activated. The timer node
+ will trigger the next node whenever the timer is triggered. This means that the
+ outgoing connection of a timer node can be triggered multiple times if a period is used.
+ Cancelling a timer node also cancels the associated timer.</listitem>
+ <listitem>Timers associated to nodes: it is also possible to add timers to event-based
+ nodes like work items, sub-flows, etc. The timers associated with these nodes are activated
+ once the node is triggered. The associated action is executed if the timer is triggered.
+ This could for example be used to send out notifications at regular time intervals when
+ the execution of a task takes too long, or signal an event or a fault in case of a time-out.
+ When the node these timers are defined for is completed, the timers are automatically
+ cancelled.</listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section>
+ <title>Assigning rules to a ruleflow group</title>
+
<para>Drools already provides some functionality to define the order in
which rules should be executed, like salience, activation groups, etc. When
dealing with (possibly a lot of) large rule-sets, managing the order in
@@ -32,9 +682,6 @@
should be considered (by specifying the order in which the ruleflow-groups should
be evaluated).</para>
- <section>
- <title>Assigning rules to a ruleflow group</title>
-
<programlisting>
rule 'YourRule'
ruleflow-group 'group1'
@@ -70,79 +717,8 @@
is harder to maintain, and makes the time-relationship implicit in the
rules), or agenda groups. However, using a ruleflow makes the order of
processing explicit, almost like a meta-rule, and makes managing more complex
- situations a lot easier. The various elements that can be used inside a ruleflow
- will be explained in more detail later.</para>
- </section>
+ situations a lot easier.</para>
- <section>
- <title>How to build a rule flow</title>
-
- <para>Ruleflows can only be created by using the graphical ruleflow editor which is
- part of the Drools plug-in for Eclipse. Once you have set up a Drools project (check
- the IDE chapter if you do not know how to do this), you can start adding ruleflows.
- When in a project, use "control+N" to launch the new wizard, or right-click the directory
- you would like to put your ruleflow in and select "New ... Other ...":</para>
-
- <figure>
- <title>Ruleflow</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="RFNewWizard.png" format="PNG"
- role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Choose the section on "Drools" and then pick "RuleFlow file".
- This will create a new .rf file.</para>
-
- <para>Next you will see the graphical ruleflow editor. Now would be a good time to
- switch to the "Drools perspective" (if you haven't done so already) - this will tweak the UI so
- it is optimal for rules. Then ensure that you can see the "properties"
- panel down the bottom of the Eclipse window, as it will be necessary to fill in the different
- properties of the elements in your ruleflow. If you cannot see the properties view, open it using
- the Menu Window - Show View - Other ..., and under the General folder select the Properties view.</para>
-
- <figure>
- <title>Groups</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="RFNameGroups.png" format="PNG"
- role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The RuleFlow editor consists of a palette, a canvas and an outline view. To add
- new elements to the canvas, select the element you would like to create in the palette
- and then add them to the canvas by clicking on the preferred location. For example,
- click on the RuleFlowGroup icon in the Component Pallette of the GUI
- - you can then draw a few rule flow groups. Clicking on an element in your ruleflow
- allows you to set the properties of that element.</para>
-
- <para>Click on a ruleflow group, and you should see the following:</para>
-
- <figure>
- <title>Group properties</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="RFGroupProperties.png"
- format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>You can see here you set the visible name, but you also need to set
- the actual group name that is used in the rules.</para>
-
- <para>Next step is to join the groups together (if its a simple sequence
- of steps) - you use this by using "create connection" from the component
- palette. You should also create an "End" node (also from the component
- palette).</para>
-
<para>In practice, if you are using ruleflow, you will most likely be
doing more then setting a simple sequence of groups to progress though.
You are more likely modeling branches of processing. In this case you use
@@ -191,7 +767,7 @@
<para>Split types (referring to the above): When you click on a split, you
will see the above properties panel. You then have to choose the type:
AND, OR, and XOR. The interesting ones are OR and XOR: if you choose OR,
- then any of the "outputs" of the split can happen (ie processing can
+ then any of the "outputs" of the split can happen (i.e. processing can
proceed in parallel down more then one path). If you chose XOR, then it
will be only one path.</para>
@@ -234,135 +810,4 @@
path specified by it will be followed.</para>
</section>
- <section>
- <title>Using a rule flow in your application</title>
-
- <para>Once you have a valid ruleflow (you can check its valid by pressing
- the green "tick" icon in the IDE), you can add a rule flow to a package
- just like a drl. However, the IDE creates two versions of your ruleflow: one containing
- the ruleflow definition (*.rfm) and one containing additional graphical information (*.rf).
- When adding a ruleflow to a package, you should make sure that you are adding the
- .rfm file to your ruleflow (and not the .rf file).
- <programlisting>
-Reader rfm = ... (rule flow reader, select your .RFM file here)
-packageBuilder.addRuleFlow(rfm);
- </programlisting>
- </para>
-
- <para>Alternatively, you can upload the .rf file to the BRMS (as a
- ruleflow asset) and it will automatically be included in packages that are
- deployed from it.</para>
-
- <para>Ruleflows are only executed if you explicitly state that they should be
- executed. This is because you could potentially define a lot of ruleflows in
- your package and the engine has no way to know when you would like to start
- each of these. To activate a particular ruleflow, you will
- need to start the process by calling the startProcess method on the working memory.
- For example, if you want to start a particular workflow after you have asserted your
- facts into the working memory, use:
- <programlisting>workingMemory.startProcess("ID_From_your_Ruleflow_properties");</programlisting>
- (The ruleflow id can be specified in the properties view when you click the background canvas of your ruleflow).
- And then call fireAllRules(). This will start executing rules, taking the order specified in the ruleflow into account.
- Thats it !</para>
-
- <para> You can also start a ruleflow process from within a rule consequence using
- <programlisting>drools.getWorkingMemory().startProcess("ID_From_your_Ruleflow_properties");</programlisting>
- </para>
- </section>
-
- <section>
- <title>Different types of nodes in a ruleflow</title>
- <para>A ruleflow is a flow chart where different types of nodes are linked using connections. It has the following properties: a (unique) id, a (display) name and a version. Global and imports can be defined that can be reused throughout the entire process. You can also specify how the connections are visualized on the canvas using the connection layout property:
- <orderedlist>
- <listitem>
- <para>manual always draws your connections as lines going straight from their start to end point (with the possibility to use intermediate break points)
- </para>
- </listitem>
- <listitem>
- <para>shortest path is similar, but it tries to go around any obstacles is might encounter between the start and end point (to avoid lines crossing nodes)
- </para>
- </listitem>
- <listitem>
- <para>manhatten draws connections by only using horizontal and vertical lines
- </para>
- </listitem>
- </orderedlist>
- </para>
-
- <figure>
- <title>The different types of ruleflow nodes</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="ruleflow_nodes.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>RuleFlow supports different types of nodes:
- <orderedlist>
- <listitem>
- <para>Start: the start of the ruleflow. A ruleflow should have exactly one start node. The start node cannot have incoming cnnections and should have one outgoing connection. It contains one property "name" which is the display name of the node. Whenever ruleflow process is started, the ruleflow will start executing here and automatically continue to the first node linked to this start node.</para>
- </listitem>
- <listitem>
- <para>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 one property "name" which is the display name of the node. When an end node is reached in the ruleflow, the ruleflow is terminated. If a ruleflow is terminated, all nodes that are still active in this ruleflow are cancelled first (which is possible if parallel paths are used).</para>
- </listitem>
- <listitem>
- <para>RuleSet: represents a set of rules. The rules are evaluated when the node is reached. A RuleFlowGroup node should have one incoming connection and one outgoing connection. It contains a property "name" which is the display name of the node, and the property "ruleflow-group" which is used to specify the name of the ruleflow-group that represents the set of rules of this RuleFlowGroup node. Rules can use the ruleflow-group attribute to become part of a ruleflow group. When a RuleSet 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 rul!
eflow will immediately continue with the next node if it encounters a ruleflow-group where there are no active rules at that point. 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. </para>
- </listitem>
- <listitem>
- <para>Split: allows you to create branches in your ruleflow. A split node should have one incoming connection and two or more outgoing connections. It contains a property "name" which is the display name of the node. There are three types of splits currently supported:
- <orderedlist>
- <listitem>
- <para>AND means that the control flow will continue in all outgoing connections simultaneously (paralellism).
- </para>
- </listitem>
- <listitem>
- <para>XOR means that exactly one of the outgoing connections will be chosen (decision). Which connection is decided 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.
- </para>
- </listitem>
- <listitem>
- <para>OR means that all outgoing connections whose condition evaluates to true are selected. Conditions are similar to the XOR split, except that the priorities are not taken into account. Note that you should 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 an outgoing connection).
- </para>
- </listitem>
- </orderedlist>
-
- </para>
- </listitem>
- <listitem>
- <para>Join: allows you to synchronize multiple branches. A join node should have two or more incoming connections and one outgoing connection. It contains a property "name" which is the display name of the node. There are three types of splits currently supported:
- <orderedlist>
- <listitem>
- <para>AND means that is will wait until all incoming branches are completed before continuing.
- </para>
- </listitem>
- <listitem>
- <para>XOR means that it continues if one of its incoming branches has been completed.
- </para>
- </listitem>
- <listitem>
- <para>Discriminator means that it continues if one of its incoming branches has been completed.
- </para>
- </listitem>
- </orderedlist>
- </para>
- </listitem>
- <listitem>
- <para>Event wait (milestone): represents a wait state. An event wait should have one incoming connection and one outgoing connection. It contains a property "name" which is the display name of the node, and the property "constraint" which specifies how long the ruleflow should wait in this state before continuing. For example, a milestone constraint in an order entry application might specify that the ruleflow should wait until (a fact in the working memory specifies that) 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 facts in the working memory is inserted, updated or removed.</para>
- </listitem>
- <listitem>
- <para>SubProcess: represents the invocation of another process from withing this ruleflow. A sub-process node should have one incoming connection and one outgoing connection. It contains a property "name" which is the display name of the node, and the property "processId" which specifies the id of the process that should be executed. When a SubProcess node is reached in the ruleflow, the engine will start the process with the given id. If the property "Wait for completion" 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 sub-process. If the property "independent" is true, the sub-process 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. A SubProcess can !
also define in- and out-mappings for variables. The value of variables in this process with given variable name in the in-mappings will be used as parameters (with the associated parameter name) when starting the process. The value of the variables in the sub-process with the given variable name in the out-mappings will be copied to the variables of this process when the sub-process has been completed. Note that can only use out-mappings when "Wait for completion" is set to true.</para>
- </listitem>
- <listitem>
- <para>Action: represents an action that should be executed in this ruleflow. An action node should have one incoming connection and one outgoing connection. It contains a property "name" which is the display name of the node, and the property "action" which specifies the action that should be executed. The action should specify which dialect is used to specify the action (e.g. Java or MVEL), and the actual action code. The action code can refer to any globals and the special 'drools' variable which implements KnowledgeHelper, and can for example be used to access the working memory (drools.getWorkingMemory()). When an action node is reached in the ruleflow, it will execute the action and continue with the next node.</para>
- </listitem>
- <listitem>
- <para>WorkItem: represents an (abstract) item of work that should be executed in this ruleflow. A WorkItem node should have one incoming connection and one outgoing connection. It contains a property "name" which is the display name of the node. The type of work is uniquely identified by the work item name. When a WorkItem node is reached in the ruleflow, it will execute start the associated work item. If the property "Wait for completion" is true, the WorkItem node will only continue if the created work item has terminated its execution (completed or aborted); otherwise it will continue immediately after starting the work item. Each type of work item can define parameters that describe that type of work. For example, an email node (work item name "Email" will define properties like 'from', 'to', 'subject' and 'text'. The user can either fill in 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). Each type of work can also define result parameters that will 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. Note that can only use out-mappings when "Wait for completion" is set to true. The user can define their own types of work items (see the section about pluggable work items).</para>
- </listitem>
- <listitem>
- <para>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. It contains a property "name" which is the display name of the node. The "TimerDelay" property specifies how long (in milliseconds) the timer should wait before triggering the first time. The "Timerperiod" specifies the timer will between two subsequenct triggers. A period of 0 means that the timer should only be executed once. When a timer node is reached in the ruleflow, it will execute the associated timer. The timer is cancelled if the timer node is cancelled (e.g. by completing the running process).</para>
- </listitem>
- </orderedlist>
- </para>
- </section>
-
</chapter>
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/EventProcess.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/EventProcess.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/FaultProcess.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/FaultProcess.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/NewRF.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/NewRF.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-Flow/ruleflow_nodes.png
===================================================================
(Binary files differ)
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-GettingStarted/Chapter-GettingStarted.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-GettingStarted/Chapter-GettingStarted.xml 2008-10-18 08:03:41 UTC (rev 23505)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-GettingStarted/Chapter-GettingStarted.xml 2008-10-18 15:39:54 UTC (rev 23506)
@@ -10,7 +10,7 @@
is a plugin for the Eclipse developement environment that allows users to
create, execute and debug Drools processes and rules.</para>
- <para>To get started, you need an Eclipse 3.3.x, as well as the Eclipse
+ <para>To get started, you need an Eclipse 3.4.x, as well as the Eclipse
Graphical Editing Framework (GEF) plugin installed. Eclipse can be downloaded
from <ulink url="http://www.eclipse.org/downloads/">
http://www.eclipse.org/downloads/</ulink> (choose either the Eclipse IDE for Java
@@ -23,16 +23,18 @@
url="http://www.jboss.org/auth/drools/downloads.html">
http://www.jboss.org/auth/drools/downloads.html</ulink> (the latest snapshot build
can also be downloaded from <ulink url="https://hudson.jboss.org/hudson/job/drools/lastSuccessfulBuild/artifact/trunk/target/">https://hudson.jboss.org/hudson/job/drools/lastSuccessfulBuild/artifact/trunk/target/</ulink>), unzip it in your eclipse
- folder and (re)start Eclipse. If installation was successful, the Drools menu
- action should appear in the top menu bar.</para>
+ folder and (re)start Eclipse. To check that installation was successful, open
+ the Drools perspective: Click the 'Open Perspective' button in the top right corner
+ of your eclipse window, select 'Other...' and pick the Drools perspective.</para>
</section>
<section>
<title>Creating your first process</title>
- <para>You should switch to the Drools perspective within Eclipse first, as this will
- open all the relevant views for you. You can do this by clicking on the Open Perspective
- button (top right of your screen) and selecting Other ... -> Drools.</para>
+ <para>If you haven't done so already, you should switch to the Drools perspective within
+ Eclipse first, as this will open all the relevant views for you. You can do this by
+ clicking on the Open Perspective button (top right of your screen) and selecting Other ...
+ -> Drools.</para>
<para>A new project wizard can be used to setup an executable project to start using
processes immediately. This will setup a basic structure, classpath, sample
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-HumanTasks/Chapter-HumanTasks.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-HumanTasks/Chapter-HumanTasks.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/Chapter-HumanTasks/Chapter-HumanTasks.xml 2008-10-18 15:39:54 UTC (rev 23506)
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+
+ <title>Human Tasks</title>
+
+ <para></para>
+
+ <section>
+ <title>Human tasks inside processes</title>
+
+ </section>
+
+ <section>
+ <title>Human task management component</title>
+
+ </section>
+
+ <section>
+ <title>Human task management interface</title>
+
+ <section>
+ <title>Eclipse integration</title>
+ </section>
+
+ </section>
+
+</chapter>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/master.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/master.xml 2008-10-18 08:03:41 UTC (rev 23505)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/en/master.xml 2008-10-18 15:39:54 UTC (rev 23506)
@@ -54,7 +54,9 @@
<xi:include href="Chapter-Flow/Chapter-RuleFlow.xml" />
<xi:include href="Chapter-RulesAndProcesses/Chapter-RulesAndProcesses.xml" />
<xi:include href="Chapter-DomainSpecificProcesses/Chapter-DomainSpecificProcesses.xml" />
+ <xi:include href="Chapter-HumanTasks/Chapter-HumanTasks.xml" />
<xi:include href="Chapter-Debugging/Chapter-Debugging.xml" />
+ <xi:include href="Chapter-Eclipse/Chapter-Eclipse.xml" />
<index/>
</book>
More information about the jboss-svn-commits
mailing list