[jboss-svn-commits] JBL Code SVN: r24650 - in labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook: en-US/Chapter-Flow and 6 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Jan 12 09:22:29 EST 2009
Author: KrisVerlaenen
Date: 2009-01-12 09:22:28 -0500 (Mon, 12 Jan 2009)
New Revision: 24650
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/WSHT-lifecycle.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_editor.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_process.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_properties.png
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Persistence/
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Persistence/audit_db.png
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-HumanTasks/Chapter-HumanTasks.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml
Log:
- updated Drools Flow docs
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml 2009-01-12 14:11:27 UTC (rev 24649)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml 2009-01-12 14:22:28 UTC (rev 24650)
@@ -550,7 +550,7 @@
<!-- 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>
+ <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 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>
@@ -559,10 +559,12 @@
<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>Content</emphasis>: The data associated with this task.</para></listitem>
+ <listitem><para><emphasis>Swimlane</emphasis>: 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.</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>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. 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.</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>
@@ -604,7 +606,7 @@
<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>
+ <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 #{expression} to embed a value in the String. The value will be retrieved when creating the work item and the #{...} will be replaced by the toString() value of the variable. The expression could simply be the name of a variable (in which case it will be resolved to the value of the variable), but more advanced MVEL expressions are possible as well, like #{person.name.firstname}.</para></listitem>
</itemizedlist>
</listitem>
@@ -639,15 +641,16 @@
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>
+ <programlisting>context.setVariable(variableName, value);</programlisting>. When using the MVEL dialect,
+ you can even access the variables directly using the variable name.</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
+ of the work item parameters (either using a parameter mapping or by using #{expression} 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>
+ <listitem>Various other nodes can also access data. For example, event nodes can store the data associated
+ to the event in a variable, exception handlers can read error data from a specific variable, etc. Check the
+ properties of the different node types for more information.</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>
<para>globals, data in working memory, etc</para>
</section>
@@ -678,11 +681,12 @@
</para>
<para>Actions have access to globals that are defined for
- the process and the context variable. The context variable can be used for
+ the process and the 'kcontext' variable. This variable is of type org.drools.runtime.process.ProcessContext and 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>
+ <listitem>Getting the current process instance. This process instance could be queried for data (name, id, processId, etc.), abort process instance, signal events (internal).</listitem>
+ <listitem>Data: getting or setting the value of variables</listitem>
+ <listitem>Accessing the KnowledgeRuntime: this allows you do things like starting a process, signalling events (external), inserting data, etc.</listitem>
</itemizedlist>
</para>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml 2009-01-12 14:11:27 UTC (rev 24649)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml 2009-01-12 14:22:28 UTC (rev 24650)
@@ -23,23 +23,31 @@
the GEF plugin as well):</para>
<para><ulink url="http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/</ulink></para>
- <para>Next you need to install the Drools Eclipse plugin. There are two ways to do
- this, (1) manually downloading and installing the plugin or (2) using the Drools
- Eclipse update site.</para>
+ <!--para>Next you need to install the Drools Eclipse plugin. There are two ways to do this,
+ (1) manually downloading and installing the plugin or (2) using the Drools Eclipse update site.</para>
+ <para><emphasis role="strong">Manual download:</emphasis-->
- <para><emphasis role="strong">Manual download:</emphasis> Download the Drools Eclipse
+ <para>Next you need to install the Drools Eclipse plugin. Download the Drools Eclipse
IDE plugin from the link below. Unzip the downloaded file in your main eclipse folder
- (so that the feature and plugin jars end up in the features and plugin directory of
- eclipse) and (re)start Eclipse.</para>
- <para><ulink url="http://www.jboss.org/auth/drools/downloads.html">http://www.jboss.org/auth/drools/downloads.html</ulink></para>
+ (do not just copy the file there, extract it so that the feature and plugin jars end
+ up in the features and plugin directory of eclipse) and (re)start Eclipse.</para>
+ <para><ulink url="http://www.jboss.org/drools/downloads.html">http://www.jboss.org/drools/downloads.html</ulink></para>
- <para><emphasis role="strong">Using the update site:</emphasis> Open up Eclipse,
+ <!--para><emphasis role="strong">Using the update site:</emphasis> Open up Eclipse,
and in the "Help" menu, select "Software Updates ...", and in the "Available Software"
- tab, click the "Add Site ..." button. TODO: all link + explanation for update site.</para>
+ tab, click the "Add Site ..." button. TODO: all link + explanation for update site.</para-->
<para>To check that the installation was successful, try opening 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>
+ select 'Other...' and pick the Drools perspective. If you cannot find the Drools perspective
+ as one of the possible perspectives, the installation probably was unsuccessful. Check
+ whether you executed each of the required steps correctly: Do you have the right version
+ of Eclipse (3.4.x)? Do you have Eclipse GEF installed (check whether the org.eclipse.gef_3.4.*.jar
+ exists in the plugins directory in your eclipse root folder)? Did you extract the Drools Eclipse
+ plugin correctly (check whether the org.drools.eclipse_*.jar exists in the plugins directory in
+ your eclipse root folder)? If you cannot find the problem, try contacting us (e.g. on irc or on
+ the user mailing list), more info can be found no our homepage here:</para>
+ <para><ulink url="http://www.jboss.org/drools/">http://www.jboss.org/drools/</ulink></para>
</section>
<section>
@@ -49,7 +57,10 @@
the necessary files to get started easily with defining and executing processes. This wizard
will setup a basic project structure, the classpath, a sample process and execution code to
get you started. To create a new Drools Project, simply left-click on the Drools action button
- (with the Drools head) in the Eclipse toolbar and select "New Drools Project". Alternatively,
+ (with the Drools head) in the Eclipse toolbar and select "New Drools Project". [Note that the
+ Drools action button only shows up in the Drools perspective. To open the Drools perspective
+ (if you haven't done so already), click the 'Open Perspective' button in the top right corner
+ of your Eclipse window, select 'Other...' and pick the Drools perspective.] Alternatively,
you could also select "File" -> "New" -> "Project ..." and in the Drools folder, select Drools
Project. This should open the following dialog:</para>
@@ -78,11 +89,11 @@
or you can simply create a new runtime on your file system from the jars included in the Drools
Eclipse plugin. Since we simply want to use the Drools version included in this plugin, we will
do the latter. Note that you will only have to do this once, next time you create a Drools project,
- it will automatically use the default Drools runtime, unless you specify otherwise.</para>
+ it will automatically use the default Drools runtime (unless you specify otherwise).</para>
<para>So if you have not yet set up a Drools runtime, click the Next button. The following dialog
- as shown below tells you that you have not yet defined a default Drools runtime and that you should
- configure the workspace settings first. Do this by clicking on the "Configure Workspace Settings ..."
+ as shown below shows up, telling you that you have not yet defined a default Drools runtime and that
+ you should configure the workspace settings first. Do this by clicking on the "Configure Workspace Settings ..."
link.</para>
<mediaobject>
@@ -95,11 +106,11 @@
<para>The dialog that pops up shows the workspace settings for Drools runtimes. The first time you
do this, the list of installed Drools runtimes is probably empty, as shown below. To create a new
runtime on your file system, click the "Add..." button. This shows a dialog where you should give
- the new runtime a name (e.g. "Drools5 runtime"), and a path to your drools runtime on your file
- system. In this tutorial, we will simply create a new Drools5 runtime from the jars embedded in the
+ the new runtime a name (e.g. "Drools 5.0.0 runtime"), and a path to your drools runtime on your file
+ system. In this tutorial, we will simply create a new Drools 5 runtime from the jars embedded in the
Drools Eclipse plugin. Click the "Create a new Drools 5 runtime ..." button and select the folder
- where you want this runtime to be created and click the "OK" button. You will see the path you
- selected show up in the previous dialog. So we're all done here as well, so click the "OK" button
+ where you want this runtime to be stored and click the "OK" button. You will see the selected path
+ show up in the previous dialog. So we're all done here as well, so click the "OK" button
here as well. You will see the newly created runtime show up in your list of Drools runtimes. Select
this runtime as the new default runtime by clicking on the check box in front of your runtime name
and click "OK". After successfully setting up your runtime, you can now finish the project creation
@@ -117,7 +128,7 @@
<orderedlist>
<listitem>
<para>ruleflow.rf : the process definition, which is a very simple process containing
- a start node (the entry points), and action node (that prints out 'Hello World') and an
+ a start node (the entry point), an action node (that prints out 'Hello World') and an
end node (the end of the process).</para>
</listitem>
<listitem>
@@ -136,8 +147,9 @@
</imageobject>
</mediaobject>
- <para>The RuleFlow editor contains a graphical representation of your process definition. It
- consists of nodes that are connected. The editor shows the overall control flow, while the
+ <para>By double-clicking the ruleflow.rf file, the process will be opened in the RuleFlow editor.
+ The RuleFlow editor contains a graphical representation of your process definition. It
+ consists of nodes that are connected to each other. The editor shows the overall control flow, while the
details of each of the elements can be viewed (and edited) in the Properties View at the bottom.
The editor contains a palette at the left that can be used to drag-and-drop new nodes, and an
outline view at the right.</para>
@@ -184,7 +196,8 @@
</section>
<section>
- <title>Executing your first process</title>
+ <title>Executing your first process</title>
+
<para>To execute this process, right-click on RuleFlowTest.java and select Run As - Java
Application. When the process in executed, the following output should appear on the
console:</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-HumanTasks/Chapter-HumanTasks.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-HumanTasks/Chapter-HumanTasks.xml 2009-01-12 14:11:27 UTC (rev 24649)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-HumanTasks/Chapter-HumanTasks.xml 2009-01-12 14:22:28 UTC (rev 24650)
@@ -9,25 +9,236 @@
<title>Human Tasks</title>
- <para></para>
-
+ <para>An important aspect of work flow is human task management. While some of the
+ work performed in a process can be executed automatically, some tasks need to be executed
+ by human actors. Drools Flow supports the use of human tasks inside processes using a
+ special human task node. This node allows process designers to define the type of task,
+ the actor(s), the data associated with the task, etc. We also have implemented a task service
+ that can be used to manage these human tasks. Users are however open to integrate any
+ other solution if they want to, as this is fully pluggable.</para>
+
+ <para>To start using human tasks inside your processes, you first need to (1) include human
+ task nodes inside your process, (2) integrate a task management component of your choice (e.g.
+ the WS-HT implementation provided by us) and (3) have end users interact with the human task
+ management component using some kind of user interface. These elements will be discussed in
+ more detail in the next sections.</para>
+
<section>
<title>Human tasks inside processes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-HumanTasks/human_task_process.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Drools Flow supports the use of human tasks inside processes using a special human task
+ node (as shown in the figure above). A human task node represents an atomic task that needs to be
+ executed by a human actor. Although Drools Flow has a special human task node for including human
+ tasks inside a process, human tasks are simply considered as any other kind of external service that
+ needs to be invoked and are therefore simply implemented as a special kind of work item. The only
+ thing that is special about the human task node is that we have added support for swimlanes, making it
+ easier to assign tasks to users (see below). A human task node contains the following properties:
+ <itemizedlist>
+ <listitem><emphasis>Id</emphasis>: The id of the node (which is unique within one node container).</listitem>
+ <listitem><emphasis>Name</emphasis>: The display name of the node.</listitem>
+ <listitem><emphasis>TaskName</emphasis>: The name of the human task.</listitem>
+ <listitem><emphasis>Priority</emphasis>: An integer indicating the priority of the human task.</listitem>
+ <listitem><emphasis>Comment</emphasis>: A comment associated with the human task.</listitem>
+ <listitem><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.</listitem>
+ <listitem><emphasis>Skippable</emphasis>: Specifies whether the human task can be skipped (i.e. the actor decides not to execute the human task).</listitem>
+ <listitem><emphasis>Content</emphasis>: The data associated with this task.</listitem>
+ <listitem><emphasis>Swimlane</emphasis>: The swimlane this human task node is part of. Swimlanes make it easy to assign multiple human tasks to the same actor. See below for more detail on how to use swimlanes.</listitem>
+ <listitem><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.</listitem>
+ <listitem><emphasis>On entry/exit actions</emphasis>: Actions that are executed upon entry / exit of this node.</listitem>
+ <listitem><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.</listitem>
+ <listitem><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. 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.</listitem>
+ <listitem><emphasis>Timers</emphasis>: Timers that are linked to this node (see the 'timers' section for more details).</listitem>
+ </itemizedlist>
+ </para>
+
+ <para>You can edit these variables in the properties view (see below) when selecting the human task
+ node, or the most important properties can also be edited by double-clicking the human task node, after
+ which a custom human task node editor is opened, as shown below as well.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-HumanTasks/human_task_properties.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-HumanTasks/human_task_editor.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Note that you could either specify the values of the different parameters (actorId, priority, content, etc.)
+ directly (in which case they will be the same for each execution of this process), or make them context-specific,
+ based on the data inside the process instance. For example, 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 #{...} will be
+ replaced by the toString() value of the variable. The expression could simply be the name of a variable (in which
+ case it will be resolved to the value of the variable), but more advanced MVEL expressions are possible as well,
+ like #{person.name.firstname}. For example, when sending an email, the body of the email could contain something
+ like "Dear #{customer.name}, ...". For other types of variables, it is possible to map the value of a variable
+ to a parameter using the parameter mapping.</para>
+
+ <section>
+ <title>Swimlanes</title>
+
+ <para>Human task nodes can be used in combination with swimlanes to assign multiple human tasks
+ to the similar actors. Tasks in the same swimlane will be assigned to the same actor. Whenever
+ the first task in a swimlane is created, and that task has an actorId specified, that actorId will
+ be assigned to the swimlane as well. All other tasks that will be created in that swimlane will use
+ that actorId as well, even if an actorId has been specified for the task as well.</para>
+
+ <para>Whenever a human task that is part of a swimlane is completed, the actorId of that swimlane is
+ set to the actorId that executed that human task. This allows for example to assign a human task to
+ a group of users, and to assign future tasks of that swimlame to the user that claimed the first task.
+ This will also automatically change the assignment of tasks if at some point one of the tasks is
+ reassigned to another user.</para>
+
+ <para>To add a human task to a swimlane, simply specify the name of the swimlane as the value of the
+ "Swimlane" parameter of the human task node. A process must also define all the swimlanes that it contains.
+ To do so, open the process properties by clicking on the background of the process and click on the
+ "Swimlanes" property. You can add new swimlanes there.</para>
+ </section>
+
</section>
<section>
<title>Human task management component</title>
+ <para>As far as the Drools Flow engine is concerned, human tasks are similar to any other external
+ service that needs to be invoked and are implemented as an extension of normal work items. As a result,
+ the process itself only contains an abstract description of the human tasks that need to be executed, and
+ a work item handler is responsible for binding this abstract tasks to a specific implementation. Using
+ our pluggable work item handler approach (see the chapter on domain-specific processes for more details),
+ users can plug in any back-end implementation.</para>
+
+ <para>We do however provide an implementation of such a human task management component based on the
+ WS-HumanTask specification. If you do not have the requirement to integrate a specific human task
+ component yourself, you can use this service. It manages the task life cycle of the tasks (creation,
+ claiming, completion, etc.) and stores the state of the task persistently. It also supports features
+ like internationalization, calendar integration, different types of assignments, delegation, deadlines,
+ etc.</para>
+
+ <para>Because we did not want to implement a custom solution when a standard is available, we chose to
+ implement our service based on the WS-HumanTask (WS-HT) specification. This specification defines in detail
+ the model of the tasks, the life cycle, and a lot of other features as the ones mentioned above. It is pretty
+ comprehensive and can be found
+ <ulink url="http://download.boulder.ibm.com/ibmdl/pub/software/dw/specs/ws-bpel4people/WS-HumanTask_v1.pdf">
+ here</ulink>.</para>
+
+ <section>
+ <title>Task life cycle</title>
+
+ <para>Looking from the perspective of the process, whenever a human task node is triggered during the
+ execution of a process instance, a human task is created. The process will only continue from that point
+ when that human task has been completed or aborted (unless of course you specify that the process does not
+ need to wait for the human task to complete, by setting the "Wait for completion" property to true). However,
+ the human task usually has a separate life cycle itself. We will now shortly introduce this life cycle, as shown
+ in the figure below. For more details, check out the WS-HumanTask specification.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-HumanTasks/WSHT-lifecycle.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>Whenever a task is created, it starts in the "Created" stage. It usually automatically transfers to the
+ "Ready" state, at which point the task will show up on the task list of all the actors that are allowed to execute
+ the task. There, it is waiting for one of these actors to claim the task, indicating that he or she will be
+ executing the task. Once a user has claimed a task, the status is changed to "Reserved". Note that a task that
+ only has one potential actor will automatically be assigned to that actor upon creation of that task. After claiming
+ the task, that user can then at some point decide to start executing the task, in which case the task status is
+ changed to "InProgress". Finally, once the task has been performed, the user must complete the task (and can specify
+ the result data related to the task), in which case the status is changed to "Completed". If the task could not be
+ completed, the user can also indicate this using a fault response (possibly with fault data associated), in which
+ case the status is changed to "Failed".</para>
+
+ <para>The life cycle explained above is the normal life cycle. The service also allows a lot of other life cycle
+ methods, like:
+ <itemizedlist>
+ <listitem>Delegating or forwarding a task, in which case it is assigned to another actor</listitem>
+ <listitem>Revoking a task, so it is no longer claimed by one specific actor but reappears on the task list of
+ all potential actors</listitem>
+ <listitem>Temporarly suspending and resuming a task</listitem>
+ <listitem>Stopping a task in progress</listitem>
+ <listitem>Skipping a task (if the task has been marked as skippable), in which case the task will not be executed</listitem>
+ </itemizedlist>
+ </para>
+
+ </section>
+
+ <section>
+ <title>Linking the task component to the Drools Flow engine</title>
+
+ <para>The task management component needs to be integrated with the Drools Flow engine just like any other external
+ service, by registering a work item handler that is responsible for translating the abstract work item (in this case
+ a human task) to a specific invocation. We have implemented such a work item handler
+ (org.drools.process.workitem.wsht.WSHumanTaskHandler in the drools-process-task module) so you can easily link this
+ work item handler like this:</para>
+ <programlisting>
+ StatefulKnowledgeSession session = ...;
+ session.getWorkItemManager().registerWorkItemHandler("Human Task", new WSHumanTaskHandler());</programlisting>
+ <para>By default, this handler will connect to the human task management component on the local machine on port 9123,
+ but you can easily change that by invoking the setConnection(ipAddress, port) method on the WSHumanTaskHandler.</para>
+ </section>
+
+ <section>
+ <title>Starting the task management component</title>
+
+ </section>
+
+ <section>
+ <title>Interacting with the task management component</title>
+
+ </section>
+
</section>
<section>
<title>Human task management interface</title>
+ <para></para>
+
<section>
<title>Eclipse integration</title>
+
+ <para></para>
</section>
</section>
+<!--
+For now he has taken a more practical approach to this to deliver something that we can use for Drools, rather than just aiming for WSHT compliance. Although we do hope to eventually make this fully WS-HT compliant, hopefully someone from the community can help us from that side.
+
+The class model, which is made persistable through EJB3, is close to complete and able to represent the whole of WSHT - except for the presentation elements, which I have left off for now, these can be easily added later but we don't have much use for them yet.
+
+For now we have chosen to do ignore the WS aspect and focus on a apache mina based client/server architecture this allows us to create a simpler and lower latency implementation for integration with our runtime and tooling, easily supports p2p and is more easily embeddable as mina is just a small JAR. The last one is important as the WSHT server needs to message events to running clients, who are typically in a wait state.
+
+The spec does not specify anything about iCalendar notifications, so kris has added this anyway. So now when someone claims a task they get two iCalendar emails one for the first start date and one for the last start date. iCalendar VEvents was chosen over the more symantically correct VTodo as there doesn't seem to be much support for the later - neither gmail or zimbra can detect a VTodo sent via an email. Maybe over time we can make this configurable and users can specify whether they want events or todos.
+
+Typically a Task has a start by date and an end by date, WSHT allows for multiple start deadlines and multiple end deadlines. Each deadline can have zero or more escalations that result in a re-assignment or a notification. WSHT doesn't specificy what form the notification takes place, this is one of their extension points. We have hooked up the notification system to integrate with our existing "work items" framework, initially with the email work item. Work items are pre made units of re-usable code, typically with GUI configuration in the flow editor, for executing actions. Later we could include a JMS or WS notification, leveraging any pre-made work items we have made.
+
+A Task can be in one of the following states:
+Created, Ready, Reserved, In Progress, Completed
+
+And supports the following main actions:
+Create, Claim, Start, Stop, Release, Suspend, Skip, Resume, Delegate, Forward, Complete, Fail.
+
+WSHT supports the following role types, which it refers to as People Assignments:
+Task Initiator, Task Owner, Potential Owners, Business Administrators, Excluded Owners, Recipients, Task Stakeholders.
+
+To get an understanding of how the WSHT life cycle works with the various allowed operations the spec pdf provides this state transition diagram which hopefully makes it all clear.
+
+WSHT Lifecycle from spec PDF
+
+The Drools Task code currently lives here, while the WSHT client/server implementation is close to complete the tooling integration will be minimal for 5.0 due to time constriants. We hope to quickly crank that up to make the tooling in eclipse and the Guvnor BRMS feature full. This is a great project for anyone wanting to get involved as it's relatively self contained and thus straight forward and no complex algorithms :) Things to do include full WSHT compliance, improved tooling including various extensions like inbox style views that support task labelling and also "read" status.
+
+
+For now here is a simple screenshot showing some of the minimal Task tooling integration into Eclipse.</para>
+-->
+
</chapter>
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml 2009-01-12 14:22:28 UTC (rev 24650)
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="./">
+
+ <title>Persistence</title>
+
+ <para>Drools Flow allows the persistent storage of the different kinds of
+ information, i.e. the process runtime state, the process definitions and the
+ history information.</para>
+
+ <section>
+ <title>Runtime state</title>
+
+ <para>Whenever a process is started, a process instance is created, which
+ represents the execution of the process in that specific context. For example,
+ when executing a process that specifies how to process a sales order, one process
+ instance is created for each sales request. The process instance represents
+ the current execution state in that specific context, and contains all the
+ information related to that process instance. Note that it only contains
+ the minimal runtime state that is needed to continue the execution of that
+ process instance at some later time (and for example does not include information
+ about the history of that process instance if that information is no longer
+ needed in the process instance at some later stage, see the history log).</para>
+
+ <para>The runtime state of an executing process can be persisted, for example
+ in a database. This allows for example to restore the state of execution of all
+ running processes in case of unexpected failure, or to temporarily remove running
+ instances from memory when they are no longer needed and restore them at some later
+ time. Drools Flow allows you to plug in different persistence strategies. By default
+ (if you do not configure the process engine otherwise), process instances are not
+ persisted.</para>
+
+ <section>
+ <title>Binary persistence</title>
+
+ <para>But Drools Flow provides a binary persistence mechanism that allows you
+ to persist the state of a process instance as a binary blob. This way, the
+ state of all running process instances can always be stored in a persistent location.
+ Note that these binary blobs usually are relatively small, as they only contain the
+ minimal execution state of the process instance. For a simple process instance, this
+ usually contains one or a few node instances (i.e. a node that is currently executing)
+ and possibly some variables.</para>
+
+ </section>
+
+ <section>
+ <title>Safe points</title>
+
+ <para>The state of a process instance is stored a so-called "safe points" during the
+ execution of the process engine. Whenever a process instance is started (or continued
+ after receiving an internal trigger it was waiting for), the engine executed the process
+ instance until no more actions can be performed. At that point, the engine has reached
+ the next safe state and the state of the process instance (and all other process instances
+ that might have been affected) is stored persistently.</para>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Process definitions</title>
+
+ <para>Process definitions are usually stored in an XML format. These files can easily be
+ stored on a file system during development. However, whenever you want to make your knowledge
+ accessible to one or more engines in production, we recommend using a knowledge repository
+ that (logically) centralizes your knowledge (in one or more knowledge repositories).</para>
+
+ <para>Guvnor is a sub-project that provides exactly that: it consists of a repository
+ for storing different kinds of knowledge (not only process definitions but also rules, object
+ models, etc.), allows easy retrieval of this knowledge (for example using WebDAV or by using
+ a rule agent that automatically downloads the information from Guvnor when creating a knowledge
+ base), and provides a web application that allows business users to view and possibly update
+ the information in the knowledge repository. Check out the Drools Guvnor documentation for
+ more information on how to do this.</para>
+ </section>
+
+ <section>
+ <title>History log</title>
+
+ <para>In many cases it is useful (if not necessary) to store information about the execution
+ on process instances, so that this information can be used afterwards for example to verify
+ what actions have been executed for a particular process instance, or to monitor and/or analyze
+ the efficiency of a particular process, etc. Storing history information in the runtime
+ database is usually not a good idea (as this would result in ever-growing runtime data,
+ and monitoring and analysis queries might influence the performance of your runtime engine).
+ That is why history information about the execution of process instances is stored separately.</para>
+
+ <para>This history log of execution information is created based on the events generated by the
+ process engine during execution. The Drools runtime engine provides a generic mechanism to listen
+ to different kinds of events. The necessary information can easily be extracted from these events
+ and persisted, for example in a database. Filters can be used to only store the information you
+ find relevant.</para>
+
+ <section>
+ <title>Persisting process events in a database</title>
+
+ <para>The drools-bam module contains an event listener that stores process-related information
+ in a database (using hibernate). The database contains two tables, one for process instance
+ information and one for node instance information (see figure below):
+ <orderedlist>
+ <listitem><emphasis>ProcessInstanceLog:</emphasis> This lists the process instance id, the
+ process (definition) id, the start date and (if applicable) the end date of all process
+ instances.</listitem>
+ <listitem><emphasis>NodeInstanceLog:</emphasis> This table contains more detailed information
+ about which nodes were actually executed inside each process instance. Whenever a node instance
+ is entered (from one of its incomming connections) or is exited (through one of its outgoing
+ connections), that information is stored in this table. It therefore stores the process instance
+ id and the process id (of the process instance it is being executed in), and the node instance id
+ and corresponding node id (in the process definition) of the node instance in question. Finally,
+ the type of event (0 = enter, 1 = exit) and the date of the event is stored as well.
+ </listitem>
+ </orderedlist>
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Persistence/audit_db.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+
+ <para>To log process history information in a database like this, you need to register the logger
+ on your session (or working memory) like this:</para>
+ <programlisting>
+ StatefulKnowledgeSession session = ...
+ new WorkingMemoryDbLogger(session);</programlisting>
+ <para>Note that this logger is just a logger like any other audit logger. This means you can add one
+ or more filters using the addFilter method to make sure that only relevant information is stored in the
+ database. If you use more than one filter, only information that is accepted by all your filters will
+ be persisted in the database.</para>
+
+ <para>To specify the database where the information should be stored, modify the hibernate.cfg.xml file.
+ By default, it uses an in memory database (H2). Check out the hibernate documentation if you do not
+ know how to do this.</para>
+
+ <para>All this information can easily be queried and can be used in a lot of different use cases, ranging
+ from creating a history log for one specific process instance to analyzing the performance of all instances
+ of a specific process. The org.drools.process.auditProcessInstanceDbLog class shows some examples on how
+ to retrieve all process instances, one specific process instance (by id), all process instances for one
+ specific process, all node instances of a specific process instance, etc. You can of course easily create
+ your own hibernate queries or access the information in the database directly.</para>
+ </section>
+
+ </section>
+
+</chapter>
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml
___________________________________________________________________
Name: svn:executable
+ *
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml 2009-01-12 14:11:27 UTC (rev 24649)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml 2009-01-12 14:22:28 UTC (rev 24650)
@@ -53,6 +53,7 @@
<xi:include href="Chapter-GettingStarted/Chapter-GettingStarted.xml" />
<xi:include href="Chapter-Flow/Chapter-RuleFlow.xml" />
<xi:include href="Chapter-API/Chapter-API.xml" />
+ <xi:include href="Chapter-Persistence/Chapter-Persistence.xml" />
<xi:include href="Chapter-ProcessModel/Chapter-ProcessModel.xml" />
<xi:include href="Chapter-RulesAndProcesses/Chapter-RulesAndProcesses.xml" />
<xi:include href="Chapter-DomainSpecificProcesses/Chapter-DomainSpecificProcesses.xml" />
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/WSHT-lifecycle.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/WSHT-lifecycle.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_editor.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_editor.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_process.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_process.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_properties.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-HumanTasks/human_task_properties.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Persistence/audit_db.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-Persistence/audit_db.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list