[jboss-svn-commits] JBL Code SVN: r26343 - in labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook: en-US/Chapter-BAM and 9 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sat May 2 14:56:36 EDT 2009
Author: laune
Date: 2009-05-02 14:56:36 -0400 (Sat, 02 May 2009)
New Revision: 26343
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-DomainSpecificProcesses/Chapter-DomainSpecificProcesses.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml
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/Chapter-Persistence/Chapter-Persistence.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-RulesAndProcesses/Chapter-RulesAndProcesses.xml
labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-RulesAndProcesses/validation.bmp
Log:
improvements
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml 2009-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-API/Chapter-API.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,23 +1,23 @@
-<?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"
+<?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>Drools Flow API</title>
- <section>
+ <section>
<title>Knowledge Base</title>
- <para>Our knowledge-based API allows you to first create a knowledge base
- that contains all the necessary knowledge. This includes of course all the
- relevant process definitions, but also other knowledge types like rules. The
- following code snippet shows how to create a knowledge base consisting of only
- one process definition: use a knowledge builder to add a resource, check for
- errors and create the knowledge base.</para>
+ <para>Our knowledge-based API allows you to first create a Knowledge Base
+ that contains all the necessary knowledge. This includes all the
+ relevant process definitions and other knowledge types like rules. The
+ following code snippet shows how to create a Knowledge Base consisting of only
+ one process definition, using a Knowledge Builder to add a resource, checking
+ for errors and, finally, creating the Knowledge Base.</para>
<programlisting>
KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
@@ -30,24 +30,24 @@
throw new IllegalArgumentException("Could not parse knowledge.");
}
KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
-kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
+kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
</programlisting>
<para>Note that the knowledge-based API allows users to add different types of
- resources (e.g. rules and processes) in almost identical ways into the same
- knowledge base. This allows user that know how to user Drools Flow to start using
- Expert of Fusion (and even integrate these different types of knowledge) almost
- instantaniously.</para>
+ resources, such as rules and processes, in almost identical ways into the same
+ Knowledge Base. This enables a user who knows how to use Drools Flow to start
+ using Drools Fusion almost instantaneously, and even to integrate these
+ different types of Knowledge.</para>
</section>
- <section>
+ <section>
<title>Session</title>
<para>Next, you should create a session to interact with the engine. Again, the
- API is knowledge-based, supporting different types of knowledge, with a specific
- extension for each knowledge type. The following code snippet shows how easy it
- is to create a session based on the earlier created knowledge base and start a
+ API is knowledge-based, supporting different types of Knowledge, with a specific
+ extension for each Knowledge Type. The following code snippet shows how easy it
+ is to create a session based on the earlier created Knowledge Base, and to start a
process.</para>
<programlisting>
@@ -55,9 +55,9 @@
ProcessInstance processInstance = ksession.startProcess("com.sample.ruleflow");
</programlisting>
- <para>The ProcessRuntime interface defines all the methods on the session for
- interacting with processes, as shown below. Check out the JavaDocs to get a detailed
- explanation for each of the methods.</para>
+ <para>The <code>ProcessRuntime</code> interface defines all the session methods
+ for interacting with processes, as shown below. Consult the Javadocs to get
+ a detailed explanation for each of the methods.</para>
<programlisting>
ProcessInstance startProcess(String processId);
@@ -70,76 +70,77 @@
</section>
- <section>
+ <section>
<title>Events</title>
- <para>Both the stateful and stateless knowledge session provide methods for
- registering (and removing) listeners. ProcessEventListeners can be used to
- listen to process-related events, like starting or completing a processes and
- triggering and leaving a node. Below the different methods of a
- ProcessEventListener are shown. The event object provides access to related
- information like the process instance and/or node instance linked to the event.
- </para>
+ <para>Both the Stateful and Stateless Knowledge Session provide methods for
+ registering and removing listeners. <code>ProcessEventListener</code> objects
+ can be used to listen to process-related events, like starting or completing
+ a process, and entering and leaving a node. Below, the different methods of a
+ <code>ProcessEventListener</code> are shown. An event object provides access
+ to related information, like the process instance and node instance linked to
+ the event.</para>
<programlisting>
public interface ProcessEventListener {
- void beforeProcessStarted(ProcessStartedEvent event);
- void afterProcessStarted(ProcessStartedEvent event);
- void beforeProcessCompleted(ProcessCompletedEvent event);
- void afterProcessCompleted(ProcessCompletedEvent event);
- void beforeNodeTriggered(ProcessNodeTriggeredEvent event);
- void afterNodeTriggered(ProcessNodeTriggeredEvent event);
- void beforeNodeLeft(ProcessNodeLeftEvent event);
- void afterNodeLeft(ProcessNodeLeftEvent event);
+ void beforeProcessStarted( ProcessStartedEvent event );
+ void afterProcessStarted( ProcessStartedEvent event );
+ void beforeProcessCompleted( ProcessCompletedEvent event );
+ void afterProcessCompleted( ProcessCompletedEvent event );
+ void beforeNodeTriggered( ProcessNodeTriggeredEvent event );
+ void afterNodeTriggered( ProcessNodeTriggeredEvent event );
+ void beforeNodeLeft( ProcessNodeLeftEvent event );
+ void afterNodeLeft( ProcessNodeLeftEvent event );
-}
-</programlisting>
+}</programlisting>
<para>An audit log can be created based on the information provided by these process
listeners. We provide various default logger implementations:
- <orderedlist>
+ <orderedlist>
<listitem>Console logger: This logger writes out all the events to the console.</listitem>
+
<listitem>File logger: This logger writes out all the events to a file using an
- XML representation. This log file can then for example be used in the IDE to generate
- a tree-based visualization of the events that occured during execution.</listitem>
- <listitem>Threaded file logger: Because a file logger only writes the events to disk
- when closing the logger (or when the number of events in the logger reaches a predefined
- level), it cannot be used when debugging processes at runtime. A threaded file logger
- writes out the events to file at a specified time interval, making it possible to use
- the logger for example to visualize the progress when debugging processes in realtime.
+ XML representation. This log file might then be used in the IDE to generate
+ a tree-based visualization of the events that occurred during execution.</listitem>
+
+ <listitem>Threaded file logger: Because a file logger writes the events to disk only
+ when closing the logger or when the number of events in the logger reaches a predefined
+ level, it cannot be used when debugging processes at runtime. A threaded file logger
+ writes the events to a file after a specified time interval, making it possible to use
+ the logger to visualize the progress in realtime, while debugging processes.
</listitem>
- </orderedlist>
+ </orderedlist>
</para>
- <para>The KnowledgeRuntimeLoggerFactory can be used to easily add a logger to your session,
- as shown below. When creating a console logger, the knowledge session for which the logger
- needs to be created needs to be passes as an argument. The file logger also requires the
- name of the log file to be created, and the threaded file logger requires the interval (in
- milliseconds) after which the events should be saved.</para>
+ <para>The <code>KnowledgeRuntimeLoggerFactory</code> let you add a logger to
+ your session, as shown below. When creating a console logger, the Knowledge Session
+ for which the logger needs to be created must be passed as an argument. The file
+ logger also requires the name of the log file to be created, and the threaded file
+ logger requires the interval (in milliseconds) after which the events should be saved.</para>
<programlisting>
-KnowledgeRuntimeLogger logger = KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "test");
-// add invocations to the process engine here, e.g. ksession.startProcess(processId);
+KnowledgeRuntimeLogger logger =
+ KnowledgeRuntimeLoggerFactory.newFileLogger( ksession, "test" );
+// add invocations to the process engine here,
+// e.g. ksession.startProcess(processId);
...
-logger.close();
-</programlisting>
+logger.close();</programlisting>
- <para>The log file can be opened in the Eclipse when using the Audit View in the Drools
- Eclipse plugin, where the events are visualized in a tree-based manner (events that occur
- between the before and after event are shown as children of that event). The following
- screenshot shows a simple example, where a process is started, resulting in the triggering
- of the start node, an action node and an end node, after which the process was completed.
- </para>
+ <para>The log file can be opened in Eclipse, using the Audit View in the Drools
+ Eclipse plugin, where the events are visualized as a tree. Events that occur
+ between the before and after event are shown as children of that event. The
+ following screenshot shows a simple example, where a process is started,
+ resulting in the activation of the Start node, an Action node and an End node,
+ after which the process was completed. </para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="PNG" role=""
- fileref="images/Chapter-API/AuditView.png"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="PNG" role=""
+ fileref="images/Chapter-API/AuditView.png"/>
+ </imageobject>
</mediaobject>
</section>
-
-</chapter>
+</chapter>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml 2009-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,84 +1,102 @@
-<?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"
+<?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>Business Activity Monitoring</title>
- <para>You need to actively monitor your processes to make sure you can detect any anomalies and react to unexpected events
- as soon as possible. Business Activity Monitoring (BAM) is related to the real-time monitoring your processes and the
- possibility to intervene directly (possibly even automatically), based on the analysis of these events.</para>
+ <para>You need to actively monitor your processes to make sure you can detect
+ any anomalies and react to unexpected events as soon as possible.
+ Business Activity Monitoring (BAM) is concerned with real-time monitoring of
+ your processes and the option of intervening directly, possibly even
+ automatically, based on the analysis of these events.</para>
- <para>Drools Flow allows users to define reports based on the events generated by the process engine, and possibly direct
- intervention in specific situations using Complex Event Processing rules (Drools Fusion), as described in the next two
- sections. Support for the entire Business Activity Monitoring requirements (including a web-based application that can
- be used to more easily interact with a running process engine, inspect its state, generate reports, etc.) will be included
- in future releases of the Drools platform.</para>
+ <para>Drools Flow allows users to define reports based on the events generated
+ by the process engine, and possibly direct intervention in specific situations
+ using complex event processing rules (Drools Fusion), as described in the next
+ two sections. Future releases of the Drools platform will include support for
+ all requirements of Business Activity Monitoring, including a web-based
+ application that can be used to more easily interact with a running process
+ engine, inspect its state, generate reports, etc.</para>
- <section>
+ <section>
<title>Reporting</title>
- <para>By adding a history logger to the process engine, all relevent events are stored in the database. This history
- log can be used to monitor and analyze the execution of your processes. We are using Eclipse BIRT (Business Intelligence
- Reporting Tool) to create reports that show the key performance indicators. It's easy to define your own reports yourself,
- using the predefined data sets containing all process history information, and any other data sources you might want to
- add yourself.</para>
+ <para>By adding a history logger to the process engine, all relevent events
+ are stored in the database. This history log can be used to monitor and
+ analyze the execution of your processes. We are using the Eclipse BIRT
+ (Business Intelligence Reporting Tool) to create reports that show the key
+ performance indicators. Its easy to define your own reports yourself,
+ using the predefined data sets containing all process history information,
+ and any other data sources you might want to add yourself.</para>
- <para>The Eclipse BIRT framework allows you to define data sets, create reports, include charts, preview your reports,
- export them on web pages, etc. We refer to the Eclipse BIRT documentation on how to define your own reports. The following
- screen shot shows a sample on how to create such a chart.</para>
+ <para>The Eclipse BIRT framework allows you to define data sets, create
+ reports, include charts, preview your reports, and export them on web pages.
+ (Consult the Eclipse BIRT documentation on how to define your own reports.)
+ The following screen shot shows a sample on how to create such a chart.</para>
- <figure>
- <title>Creating a report using Eclipse BIRT</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-BAM/EventingReportEdit.png" format="PNG" role="" />
- </imageobject>
+ <figure>
+ <title>Creating a report using Eclipse BIRT</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-BAM/EventingReportEdit.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
- </figure>
+ </figure>
- <para>The next figure shows a simple report based on some history data, showing the number of requests every hour, and the
- average completion time of the request in that hour. These charts could be used to check for an unexpected drop or rise
- of requests, an increase in the average processing time, etc. These charts could signal possible problems before the
+ <para>The next figure displays a simple report based on some history data,
+ showing the number of requests per hour and the average completion time
+ of the request during that hour. These charts could be used to check for an
+ unexpected drop or rise of requests, an increase in the average processing
+ time, etc. These charts could signal possible problems before the
situation really gets out of hand.</para>
- <figure>
- <title>The eventing report</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-BAM/EventingReport.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
+ <figure>
+ <title>The eventing report</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-BAM/EventingReport.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
</figure>
</section>
-
- <section>
- <title>Direct intervention</title>
- <para>Reports can be used to visualize an overview of the current state of your processes, they do however rely on
- a human actor to take action based on the information in these charts. We do however allow users to define how to
- respond automatically to specific circumstances.</para>
+ <section>
+ <title>Direct Intervention</title>
- <para>Drools Fusion provides numerous features that make it easy to process large sets of events. This can be used
- to monitor the process engine itself. This can be achieved by adding a listener to the engine that forwards all
- related process events (whenever a process instance is started / completed or when a specific node is triggered during
- the execution of your process instances) to a session responsible for processing these events (this could be the same
- session as the one executing the processes or it could be an independent session as well). Complex Event Processing
- (CEP) rules could then be used to specify how to process these events. For example, these rules could generate higher-
- level business events based on (a specific occurrence of) low-level process events. The rules could also specify
- how to respond to specific situations.</para>
+ <para>Reports can be used to visualize an overview of the current state
+ of your processes, but they rely on a human actor to take action
+ based on the information in these charts. However, we allow users to
+ define automatic responses to specific circumstances.</para>
- <para>The next section shows a sample rule that accumulates all start process events for one specific order process
- over the last hour (using the sliding windows support). This rule prints out an error message if more than 1000 process
- instances were started in the last hour (e.g. to detect possible overload of the server). Note that, in a realistic
- setting, this would probably be replaced by sending an email or other form of notification to the responsible instead
- of the simple logging.</para>
+ <para>Drools Fusion provides numerous features that make it easy to
+ process large sets of events. This can be used to monitor the process
+ engine itself. This can be achieved by adding a listener to the engine
+ that forwards all related process events, such as the start and completion
+ of a process instance, or the triggering of a specific node, to a session
+ responsible for processing these events. This could be the same session
+ as the one executing the processes, or an independent session as well.
+ Complex Event Processing (CEP) rules could then be used to specify how
+ to process these events. For example, these rules could generate
+ higher-level business events based on a specific occurrence of low-level
+ process events. The rules could also specify how to respond to specific
+ situations.</para>
+ <para>The next section shows a sample rule that accumulates all start
+ process events for one specific order process over the last hour, using
+ the "sliding window" support. This rule prints out an error message if
+ more than 1000 process instances were started in the last hour (e.g., to
+ detect a possible overload of the server). Note that, in a realistic
+ setting, this would probably be replaced by sending an email or other
+ form of notification to the responsible instead of the simple logging.</para>
+
<programlisting>
declare ProcessStartedEvent
@role( event )
@@ -87,27 +105,28 @@
dialect "mvel"
rule "Number of process instances above threshold"
- when
- Number( nbProcesses : intValue > 1000 )
- from accumulate(
- e: ProcessStartedEvent( processInstance.processId == "com.sample.order.OrderProcess" )
- over window:size(1h),
- count(e) )
- then
- System.err.println(
- "WARNING: Number of order processes in the last hour above 1000: " + nbProcesses );
+when
+ Number( nbProcesses : intValue > 1000 )
+ from accumulate(
+ e: ProcessStartedEvent( processInstance.processId == "com.sample.order.OrderProcess" )
+ over window:size(1h),
+ count(e) )
+then
+ System.err.println( "WARNING: Number of order processes in the last hour above 1000: " +
+ nbProcesses );
end</programlisting>
- <para>These rules could even be used to automatically alter the behaviour of a process at runtime based on the
- events generated by the engine. For example, whenever a specific situation is detected, additional rules could
- be added to the knowledge base to dynamically modify the behaviour of the process. For example, whenever
- a large amount of user requests within a specific time frame are detected, additional validation could be added
- to the process (for example automatically add an additional step to the process to have the end user fill in a
- captcha to prevent scripting attacks, but only if the number of requests on the process engine is above a specific
- treshold). Or additional logging rules could be deployed whenever problems are detected to log additional
- information (and this only when errors are detected, not during normal operation). These rules could then be
- removed from the knowledge base again, once they are no longer needed.</para>
+ <para>These rules could even be used to alter the behavior of a process
+ automatically at runtime, based on the events generated by the engine.
+ For example, whenever a specific situation is detected, additional rules
+ could be added to the Knowledge Base to modify process behavior. For instance,
+ whenever a large amount of user requests within a specific time frame are
+ detected, an additional validation could be added to the process, enforcing
+ some sort of flow control to reduce the frequency of incoming requests.
+ There is also the possibility of deploying additional logging rules as the
+ consequence of detecting problems. As soon as the situtation reverts back to
+ normal, such rules would be removed again.</para>
</section>
-</chapter>
+</chapter>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-DomainSpecificProcesses/Chapter-DomainSpecificProcesses.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-DomainSpecificProcesses/Chapter-DomainSpecificProcesses.xml 2009-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-DomainSpecificProcesses/Chapter-DomainSpecificProcesses.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,12 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
+<chapter id="ch.Domain_Specific_Processes" 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>Domain-specific processes</title>
+ <title id="ch.Domain_Specific_Processes.title">Domain-specific processes</title>
<section>
<title>Introduction</title>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml 2009-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Eclipse/Chapter-Eclipse.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,21 +1,22 @@
-<?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"
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ch.Drools_Eclipse_IDE_Features"
+ 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>Drools Eclipse IDE features</title>
-
+
+ <title id="ch.Drools_Eclipse_IDE_Features,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>Drools Runtimes</title>
+ <section>
+ <title>Drools Runtimes</title>
- <para>A Drools runtime is a collection of jars on your file system that represent
+ <para>A Drools runtime is a collection of jar files that represent
one specific release of the Drools project jars. To create a runtime, you must
point the IDE to the release of your choice. If you want to create a new runtime
based on the latest Drools project jars included in the plugin itself, you can also
@@ -24,39 +25,41 @@
the appropriate runtime for that project specifically.</para>
<section>
- <title>Defining a Drools runtime</title>
+ <title>Defining a Drools Runtime</title>
- <para>You are required to define one or more Drools runtimes using the Eclipse preferences
- view. To open up your preferences, in the menu Window select the Preferences
- menu item. A new preferences dialog should show all your preferences. On the
+ <para>To define one or more Drools runtimes using the Eclipse preferences
+ view you open up your Preferences, by selecting the "Preferences" menu item
+ in the menu "Window". A "Preferences" dialog should show all your settings. On the
left side of this dialog, under the Drools category, select "Installed Drools
runtimes". The panel on the right should then show the currently defined Drools
- runtimes. If you have not yet defined any runtimes, it should like something like
+ runtimes. If you have not yet defined any runtimes, it should look like
the figure below.</para>
- <mediaobject>
+ <mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes.png" format="PNG" role="" />
- </imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Eclipse/drools-runtimes.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
- <para>To define a new Drools runtime, click on the add button. A dialog as shown
- below should pop up, requiring the name for your runtime and the location on your
- file system where it can be found.</para>
+ <para>To define a new Drools runtime, click on the add button. A dialog such
+ as the one shown below should pop up, asking for the name of your runtime and
+ the location on your file system where it can be found.</para>
- <mediaobject>
+ <mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-add.png" format="PNG" role="" />
- </imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-add.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
<para>In general, you have two options:</para>
- <orderedlist>
- <listitem><para>If you simply want to use the default jars as included in the Drools
- Eclipse plugin, you can create a new Drools runtime automatically by clicking the
- "Create a new Drools 5 runtime ..." button. A file browser will show up, asking
- you to select the folder on your file system where you want this runtime to be
- created. The plugin will then automatically copy all required dependencies to
+ <orderedlist>
+ <listitem><para>If you simply want to use the default jar files as included
+ in the Drools Eclipse plugin, you can create a new Drools runtime automatically
+ by clicking the "Create a new Drools 5 runtime ..." button. A file browser
+ will show up, asking you to select the folder on your file system where you
+ want this runtime to be created. The plugin will then automatically copy
+ all required dependencies to
the specified folder. After selecting this folder, the dialog should look like
the figure shown below.</para></listitem>
@@ -67,22 +70,23 @@
jars.</para></listitem>
</orderedlist>
- <mediaobject>
+ <mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-add2.png" format="PNG" role="" />
- </imageobject>
+ <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-add2.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
<para>After clicking the OK button, the runtime should show up in your table of installed
Drools runtimes, as shown below. Click on checkbox in front of the newly created runtime
to make it the default Drools runtime. The default Drools runtime will be used as the
- runtime of all your Drools project that have not selected a project-specific runtime.
+ runtime of all your Drools project that have not selected a project-specific runtime.
</para>
-
- <mediaobject>
+
+ <mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes2.png" format="PNG" role="" />
- </imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Eclipse/drools-runtimes2.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
<para>You can add as many Drools runtimes as you need. For example, the screenshot below
@@ -90,10 +94,11 @@
Drools 5.0.0 runtime and a Drools 5.0.0.SNAPSHOT runtime. The Drools 5.0.0 runtime is
selected as the default one.</para>
- <mediaobject>
+ <mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes3.png" format="PNG" role="" />
- </imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Eclipse/drools-runtimes3.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
<para>Note that you will need to restart Eclipse if you changed the default runtime and
@@ -106,10 +111,10 @@
<title>Selecting a runtime for your Drools project</title>
<para>Whenever you create a Drools project (using the New Drools Project wizard or by
- converting an existing Java project to a Drools project using the "Convert to Drools
- Project" action that is shown when you are in the Drools perspective and you right-click
- an existing Java project), the plugin will automatically add all the required jars to
- the classpath of your project.</para>
+ converting an existing Java project to a Drools project using the action
+ "Convert to Drools Project" that is shown when you are in the Drools perspective
+ and you right-click an existing Java project), the plugin will automatically add all
+ the required jars to the classpath of your project.</para>
<para>When creating a new Drools project, the plugin will automatically use the default
Drools runtime for that project, unless you specify a project-specific one. You can do
@@ -119,38 +124,40 @@
preferences showing the currently installed Drools runtimes will be opened, so you can
add new runtimes there.</para>
- <mediaobject>
+ <mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-newproject.png" format="PNG" role="" />
- </imageobject>
+ <imagedata align="center"
+ fileref="images/Chapter-Eclipse/drools-runtimes-newproject.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
<para>You can change the runtime of a Drools project at any time by opening the project
- properties (right-click the project and select Properties) and selecting the Drools
- category, as shown below. Check the "Enable project specific settings" checkbox and select
+ properties and selecting the Drools category, as shown below. Mark the
+ "Enable project specific settings" checkbox and select
the appropriate runtime from the drop-down box. If you click the "Configure workspace
settings ..." link, the workspace preferences showing the currently installed Drools
runtimes will be opened, so you can add new runtimes there. If you deselect the "Enable
project specific settings" checkbox, it will use the default runtime as defined in your
global preferences.</para>
- <mediaobject>
+ <mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/drools-runtimes-project.png" format="PNG" role="" />
- </imageobject>
+ <imagedata align="center"
+ fileref="images/Chapter-Eclipse/drools-runtimes-project.png" format="PNG" role="" />
+ </imageobject>
</mediaobject>
</section>
- </section>
+ </section>
- <section>
- <title>Process skins</title>
+ <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>The concept of <emphasis>process skins</emphasis> provides a way of
+ control the visualization of the different nodes of a processd. You may
+ change the visualization of the various node types to the way you prefer
+ by implementing your own <code>SkinProvider</code>.</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
@@ -159,31 +166,35 @@
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>
+ <para>As an 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="images/Chapter-Eclipse/RuleFlow.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Eclipse/RuleFlow.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
- <para>Simply by switching the preferred process skin in the Drools preferences ...</para>
+ <para>You may now change the preferred process skin in the Drools Preferences dialog:</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/preferences.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Eclipse/preferences.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
- <para>and then reopening the editor shows the same process using the BPMN skin ...</para>
+ <para>After reopening the editor, the same process is displayed using the BPMN skin.</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Eclipse/BPMN.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Eclipse/BPMN.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
</section>
-
-</chapter>
+
+</chapter>
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-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,21 +1,21 @@
-<?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>Rule Flow</title>
-
- <figure>
- <title>Ruleflow</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Flow/RuleFlow.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
+<?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>Rule Flow</title>
+
+ <figure>
+ <title>Ruleflow</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/RuleFlow.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
</figure>
<para>A RuleFlow is a process that describes the order in which a series of steps need to
@@ -23,262 +23,271 @@
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>
+ 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>
+ XML Schema definition for Drools processes.</listitem>
<listitem>By directly creating a process using the Process API.</listitem>
</orderedlist>
</para>
- <section>
- <title>Using the graphical RuleFlow editor</title>
+ <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="images/Chapter-Flow/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="images/Chapter-Flow/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>
+ you can start adding processes. When in a project, launch the "New" wizard: use Ctrl+N
+ or right-click the directory you would like to put your ruleflow in and select
+ "New", then "Other...". Choose the section on "Drools" and then pick "RuleFlow file".
+ This will create a new .rf file.</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>
+ <figure>
+ <title>Creating a new RuleFlow file</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/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 user interface so that 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", then "Show View" and
+ "Other...", and under the "General" folder select the Properties View.</para>
+
+ <figure>
+ <title>New RuleFlow process</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Flow/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 "Components"
+ palette of the GUI: you can then draw a few rule flow groups. Clicking on an
+ element in your rule flow allows you to set the properties of that element. You
+ can connect the nodes (as long as it is permitted by the different types
+ of nodes) by using "Connection Creation" from the "Components" 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>
+ <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>
+ <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-5.0/process"
- xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
- xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.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>
+<?xml version="1.0" encoding="UTF-8"?>
+<process xmlns="http://drools.org/drools-5.0/process"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
+ xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.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>
+ <para>The process XML file should consist of exactly one <process> element.
+ This element contains parameters related to the process (its type, name, id and
+ package name), and consists of three 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,
+ and a <connections> section that contains the connections between all the nodes
+ in the process. In the nodes section, there is a specific element for each node,
+ defining the various parameters and, possibly, sub-elements for that node type.</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. A "fluent API" is provided that allows you to easily construct
- processes in a readable manner using factories. At the end, you can validate the process that you were
- constructing manually. Some examples about how to build processes using this fluent API are added below.</para>
+ <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 packages <code>org.drools.workflow.core</code> and
+ <code>org.drools.workflow.core.node</code>. A "fluent API" is provided that
+ allows you to easily construct processes in a readable manner using factories.
+ At the end, you can validate the process that you were constructing manually.
+ Some examples about how to build processes using this fluent API are added below.</para>
- <section>
+
+ <section>
<title>Example 1</title>
<para>This is a simple example of a basic process with a ruleset node only:
<programlisting>
- RuleFlowProcessFactory factory =
- RuleFlowProcessFactory.createProcess("org.drools.HelloWorldRuleSet");
- factory
- // Header
- .name("HelloWorldRuleSet")
- .version("1.0")
- .packageName("org.drools")
- // Nodes
- .startNode(1).name("Start").done()
- .ruleSetNode(2)
- .name("RuleSet")
- .ruleFlowGroup("someGroup").done()
- .endNode(3).name("End").done()
- // Connections
- .connection(1, 2)
- .connection(2, 3);
- RuleFlowProcess process = factory.validate().getProcess();
- </programlisting>
+RuleFlowProcessFactory factory =
+ RuleFlowProcessFactory.createProcess("org.drools.HelloWorldRuleSet");
+factory
+ // Header
+ .name("HelloWorldRuleSet")
+ .version("1.0")
+ .packageName("org.drools")
+ // Nodes
+ .startNode(1).name("Start").done()
+ .ruleSetNode(2)
+ .name("RuleSet")
+ .ruleFlowGroup("someGroup").done()
+ .endNode(3).name("End").done()
+ // Connections
+ .connection(1, 2)
+ .connection(2, 3);
+RuleFlowProcess process = factory.validate().getProcess();</programlisting>
</para>
- <para>You can see that we start by calling the static createProcess() method
- from the RuleFlowProcessFactory class. This method creates a new process
- with the given id and returns the RuleFlowProcessFactory that can be used to
- create the process. A typical process consists of three parts: a header part
- that contains global elements like the name of the process, imports, variables,
- etc. The nodes section contains all the different nodes that are part of the
- process and finally the connections section links these nodes to each other
+ <para>You can see that we start by calling the static <code>createProcess()</code>
+ method from the <code>RuleFlowProcessFactory</code> class. This method creates
+ a new process with the given id and returns the <code>RuleFlowProcessFactory</code>
+ that can be used to create the process. A typical process consists of three parts.
+ The header part comprises global elements like the name of the process, imports,
+ variables, etc. The nodes section contains all the different nodes that are part of the
+ process. The connections section finally links these nodes to each other
to create a flow chart.</para>
- <para>So in this example, the header contains the name and the version of the
- process and the package name. After that you can start adding nodes to the
- current process. If you have auto-completion you can see that you different
- methods to create each of the supported node types at your disposal.</para>
+ <para>In this example, the header contains the name and the version of the
+ process and the package name. After that, you can start adding nodes to the
+ current process. If you have auto-completion you can see that you have
+ different methods to create each of the supported node types at your disposal.</para>
<para>When you start adding nodes to the process, in this example by calling
- the startNode(), ruleSetNode() and endNode() methods, you can see that these
- methods return a specific NodeFactory, that allows you to set the properties
- of that node. Once you have finished configuring that specific node, the
- done() method returns you to the current RuleFlowProcessFactory so you can add
- more nodes if necessary.</para>
+ the <code>startNode()</code>, <code>ruleSetNode()</code> and <code>endNode()</code>
+ methods, you can see that these methods return a specific <code>NodeFactory</code>,
+ that allows you to set the properties of that node. Once you have finished
+ configuring that specific node, the <code>done()</code> method returns you to the
+ current <code>RuleFlowProcessFactory</code> so you can add more nodes, if necessary.</para>
- <para>When you finised adding nodes you must connect them by creating connections
- between them. This can be done by calling the connection method, which will link
- the earlier created nodes.</para>
+ <para>When you are finished adding nodes, you must connect them by creating
+ connections between them. This can be done by calling the method
+ <code>connection</code>, which will link previously created nodes.</para>
- <para>Finally, you can validate the generated process by calling the validate()
- method and retrieve the create RuleFlowProcess object.</para>
+ <para>Finally, you can validate the generated process by calling the
+ <code>validate()</code> method and retrieve the created
+ <code>RuleFlowProcess</code> object.</para>
</section>
- <section>
+ <section>
<title>Example 2</title>
<para>This example is using Split and Join nodes:
<programlisting>
- RuleFlowProcessFactory factory =
- RuleFlowProcessFactory.createProcess("org.drools.HelloWorldJoinSplit");
- factory
- // Header
- .name("HelloWorldJoinSplit")
- .version("1.0")
- .packageName("org.drools")
- // Nodes
- .startNode(1).name("Start").done()
- .splitNode(2).name("Split").type(Split.TYPE_AND).done()
- .actionNode(3).name("Action 1").action("mvel", "System.out.println(\"Inside Action 1\")").done()
- .actionNode(4).name("Action 2").action("mvel", "System.out.println(\"Inside Action 2\")").done()
- .joinNode(5).type(Join.TYPE_AND).done()
- .endNode(6).name("End").done()
- // Connections
- .connection(1, 2)
- .connection(2, 3)
- .connection(2, 4)
- .connection(3, 5)
- .connection(4, 5)
- .connection(5, 6);
- RuleFlowProcess process = factory.validate().getProcess();
- </programlisting>
+RuleFlowProcessFactory factory =
+ RuleFlowProcessFactory.createProcess("org.drools.HelloWorldJoinSplit");
+factory
+ // Header
+ .name("HelloWorldJoinSplit")
+ .version("1.0")
+ .packageName("org.drools")
+ // Nodes
+ .startNode(1).name("Start").done()
+ .splitNode(2).name("Split").type(Split.TYPE_AND).done()
+ .actionNode(3).name("Action 1")
+ .action("mvel", "System.out.println(\"Inside Action 1\")").done()
+ .actionNode(4).name("Action 2")
+ .action("mvel", "System.out.println(\"Inside Action 2\")").done()
+ .joinNode(5).type(Join.TYPE_AND).done()
+ .endNode(6).name("End").done()
+ // Connections
+ .connection(1, 2)
+ .connection(2, 3)
+ .connection(2, 4)
+ .connection(3, 5)
+ .connection(4, 5)
+ .connection(5, 6);
+RuleFlowProcess process = factory.validate().getProcess();</programlisting>
</para>
- <para>This shows a simple split / join example. As you can see, split nodes can have multiple outgoing
- connections and joins multipe incomming connections. To understand the behaviour of the different types
- of split and join nodes, take a look at the documentation for each of these nodes.</para>
+ <para>This shows a simple example using Split and Join nodes. As you can see,
+ a Split node can have multiple outgoing connections, and a Join node multiple
+ incoming connections. To understand the behavior of the different types
+ of Split and Join nodes, take a look at the documentation for each of these
+ nodes.</para>
</section>
- <section>
+ <section>
<title>Example 3</title>
<para>Now we show a more complex example with a ForEach node, where we have nested nodes:
<programlisting>
- RuleFlowProcessFactory factory =
- RuleFlowProcessFactory.createProcess("org.drools.HelloWorldForeach");
- factory
- // Header
- .name("HelloWorldForeach")
- .version("1.0")
- .packageName("org.drools")
- // Nodes
- .startNode(1).name("Start").done()
- .forEachNode(2)
- // Properties
- .linkIncomingConnections(3)
- .linkOutgoingConnections(4)
- .collectionExpression("persons")
- .variable("child", new ObjectDataType("org.drools.Person"))
- // Nodes
- .actionNode(3)
- .action("mvel", "System.out.println(\"inside action1\")").done()
- .actionNode(4)
- .action("mvel", "System.out.println(\"inside action2\")").done()
- // Connections
- .connection(3, 4)
- .done()
- .endNode(5).name("End").done()
- // Connections
- .connection(1, 2)
- .connection(2, 5);
- RuleFlowProcess process = factory.validate().getProcess();
- </programlisting>
+RuleFlowProcessFactory factory =
+ RuleFlowProcessFactory.createProcess("org.drools.HelloWorldForeach");
+factory
+ // Header
+ .name("HelloWorldForeach")
+ .version("1.0")
+ .packageName("org.drools")
+ // Nodes
+ .startNode(1).name("Start").done()
+ .forEachNode(2)
+ // Properties
+ .linkIncomingConnections(3)
+ .linkOutgoingConnections(4)
+ .collectionExpression("persons")
+ .variable("child", new ObjectDataType("org.drools.Person"))
+ // Nodes
+ .actionNode(3)
+ .action("mvel", "System.out.println(\"inside action1\")").done()
+ .actionNode(4)
+ .action("mvel", "System.out.println(\"inside action2\")").done()
+ // Connections
+ .connection(3, 4)
+ .done()
+ .endNode(5).name("End").done()
+ // Connections
+ .connection(1, 2)
+ .connection(2, 5);
+RuleFlowProcess process = factory.validate().getProcess();</programlisting>
</para>
<para>Here you can see how we can include a ForEach node with nested action nodes.
- Note the linkIncommingConnections() and linkOutgoingConnections() methods that are
- called to link the foreach node with the internal action node. These methods are
- used to specify what the first and last nodes are inside the ForEach composite node.
- </para>
+ Note the <code>linkIncomingConnections()</code> and
+ <code>linkOutgoingConnections()</code> methods that are
+ called to link the ForEach node with the internal action node.
+ These methods are used to specify the first and last nodes inside the ForEach
+ composite node.</para>
</section>
@@ -286,26 +295,28 @@
</section>
- <section>
- <title>Using a process in your application</title>
+ <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 knowledge base that contain
- the definition of the process; and (2) you need to start the process by creating
+ within your application: (1) you need to create a Knowledge Base that contains
+ 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 knowledge base</emphasis>: Once you
- have a valid process, you can add the process to the knowledge base (note
- that this is almost identical to adding rules to the knowledge base, except
- for the type of knowledge added):</para>
+ <listitem><para><emphasis>Creating a Knowledge Base</emphasis>: Once you
+ have a valid process, you can add the process to the Knowledge Base. Note
+ that this is almost identical to adding rules to the Knowledge Base, except
+ for the type of knowledge added:</para>
<programlisting>
KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
-kbuilder.add(ResourceFactory.newClassPathResource("MyProcess.rf"), ResourceType.DRF);</programlisting>
- <para>After adding all your knowledge to the builder (you can add more than one
- process or even rules), you should probably check whether the process (and/or rules)
- have been parsed correctly and write out any errors like this:</para>
+kbuilder.add( ResourceFactory.newClassPathResource("MyProcess.rf"),
+ ResourceType.DRF );</programlisting>
+ <para>After adding all your knowledge to the builder (you can add more
+ than one process, and even rules), you should probably check whether the
+ process (and rules) have been parsed correctly and write out any errors
+ like this:</para>
<programlisting>
KnowledgeBuilderErrors errors = kbuilder.getErrors();
if (errors.size() > 0) {
@@ -314,557 +325,1140 @@
}
throw new IllegalArgumentException("Could not parse knowledge.");
}</programlisting>
- <para>Next you need to create the knowledge base that contains all the necessary
+ <para>Next, you need to create the Knowledge Base that contains all the necessary
processes (and rules) like this:</para>
<programlisting>
KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
-kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());</programlisting>
+kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());</programlisting>
</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 knowledge base 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:
+ <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
+ Knowledge Base 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 it by calling the <code>startProcess</code> method on your session.
+ For example:
<programlisting>
StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
-ksession.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 ksession.fireAllRules() method to make sure the rules are
- executed as well. That's it!</para>
- <para>You can also specify additional parameters that are used to pass on input data
- to the process, using the startProcess(String processId, Map parameters)
- method, that takes an additional set of parameters as name-value pairs. These parameters
- are then copied to the newly created process instance as top-level variables of the process.
- </para>
- <para>You can also start a process from within a rule consequence, using
- <programlisting>kcontext.getKnowledgeRuntime().startProcess("com.sample.MyProcess");</programlisting>
+ksession.startProcess("com.sample.MyProcess");</programlisting>
+ The parameter of the <code>startProcess</code> method represents the id
+ of the process that needs to be started. This process id needs to be
+ specified as a property of the process, 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 <code>ksession.fireAllRules()</code> method to
+ make sure the rules are executed as well. That's it!</para>
+
+ <para>You may specify additional parameters that are used to pass
+ on input data to the process, using the
+ <code>startProcess(String processId, Map parameters)</code> method, which
+ takes an additional set of parameters as name-value pairs. These parameters
+ are then copied to the newly created process instance as top-level variables
+ of the process.</para>
+
+ <para>You can also start a process from within a rule consequence, using
+ <programlisting>
+kcontext.getKnowledgeRuntime().startProcess("com.sample.MyProcess");</programlisting>
</para></listitem>
- </orderedlist>
-
+ </orderedlist>
+
</section>
- <section>
- <title>Detailed explanation of the different node types</title>
+ <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:
+ <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>
+ <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 section
+ <quote><link linkend='sec.data' endterm="sec.data.title"/></quote>
+ for details.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Swimlanes</emphasis>: Specify the actor responsible for the
+ execution of human tasks. See chapter
+ <quote><link linkend='ch.Human_Tasks' endterm="ch.Human_Tasks.title"/></quote>
+ for details.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Exception Handlers</emphasis>: Specify the behaviour when a fault
+ occurs in the process. See section
+ <quote><link linkend='sec.exceptions' endterm="sec.exceptions.title"/></quote>
+ for 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
+ it might encounter between the start and end point, to avoid lines crossing
+ nodes.</para>
+ </listitem>
+ <listitem>
+ <para>'Manhattan' 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:
+ </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="images/Chapter-Flow/ruleflow_nodes.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
+ <figure>
+ <title>The different types of ruleflow nodes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/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>
+ <!-- START -->
+ <listitem>
+ <para><emphasis role="strong">Start</emphasis>: The start of the ruleflow.
+ A ruleflow should have exactly one start node, which cannot have
+ incoming connections and should have one outgoing connection. Whenever a
+ RuleFlow process is started, execution will start at this node and
+ automatically continue to the first node linked to this start node, and
+ so on. It contains the following properties:</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>
+ <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 or
+ constraint 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>
+
+ <!-- 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>
+ <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 for
+ the entire process (default) or just for the path. If the process is
+ terminated, all nodes that are still active (on parallel paths) in this
+ ruleflow are cancelled. Non-terminating End nodes are simply ends for
+ some path, while other parallel paths still continue.</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>
+ <!-- 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 <kw>ruleflow-group</kw> attribute in the header. When a RuleFlowGroup node
+ is reached in the ruleflow, the engine will start executing rules that are
+ part of the corresponding ruleflow-group (if any). Execution will
+ automatically continue to the next node if there are no more active rules in
+ this ruleflow group. This means that, during the execution of a ruleflow group,
+ it is possible that new activations belonging to the currently active
+ ruleflow group are added to the Agenda due to changes made to the facts by
+ the other rules. Note that the ruleflow will immediately continue with the
+ next node if it encounters a ruleflow group where there are no active rules
+ at that time. If the ruleflow group was already active, the ruleflow group
+ will remain active and exeution will only continue if all active rules of the
+ ruleflow group has been completed. It contains the following properties:</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>
+ <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 section
+ <quote><link linkend='sec.timers' endterm="sec.timers.title"/></quote>
+ for 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>
+
+ <!-- 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 Split nodes currently
+ supported:
+ <itemizedlist>
+ <listitem>
+ <para>AND means that the control flow will continue in all outgoing
+ connections simultaneously.</para>
+ </listitem>
+ <listitem>
+ <para>XOR means that exactly one of the outgoing connections will
+ be chosen. The decision is made by evaluating the constraints
+ that are linked to each of the outgoing connections. Constraints are
+ specified using the same syntax as the left-hand side of a rule. The
+ constraint with the <emphasis>lowest</emphasis> 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 <emphasis>high</emphasis>
+ 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 no priorities are taken into account. Note that you should
+ make sure that at least one of the outgoing connections will evaluate
+ to true at runtime because the ruleflow will throw an exception at
+ runtime if it cannot determine an outgoing connection.
+ </para>
+ </listitem>
</itemizedlist>
- It contains the following properties:
- </para>
+ 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>
+ <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, i.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. If it is triggered from more than one incoming connection, it will trigger the next node for each of those triggers.
- </para>
- </listitem>
- <listitem>
- <para>Discriminator means that it continues if one of its incoming branches has been completed. At that point, it will wait until all other connections have been triggered as well. At that point, it will reset, so that it can trigger again when one of its incoming branches has been completed.
- </para>
- </listitem>
- <listitem>
- <para>n-of-m means that it continues if n of its m incoming branches have been completed. The n variable could either be hardcoded to a fixed value, or could also refer to a process variable that will contain the number of incoming branches to wait for.
- </para>
- </listitem>
- </itemizedlist>
+ <!-- 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 four types of splits currently supported:
+ <itemizedlist>
+ <listitem>
+ <para>AND means that is will wait until <emphasis>all</emphasis> incoming
+ branches are completed before continuing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>XOR means that it continues as soon as <emphasis>one</emphasis> of its
+ incoming branches has been completed. If it is triggered from more than one
+ incoming connection, it will trigger the next node for each of those triggers.</para>
+ </listitem>
+ <listitem>
+ <para>Discriminator means that it continues if one of its incoming
+ branches has been completed. Completions of other incoming branches
+ are registered until all connections have completed. At that point, the
+ node will be reset, so that it can trigger again when one of its
+ incoming branches has been completed once more.</para>
+ </listitem>
+ <listitem>
+ <para>n-of-m means that it continues if <emphasis>n</emphasis> of its
+ <emphasis>m</emphasis> incoming branches
+ have been completed. The variable <emphasis>n</emphasis> could either
+ be hardcoded to a fixed value, or refer to a process variable that will
+ contain the number of incoming branches to wait for.</para>
+ </listitem>
+ </itemizedlist>
It contains the following properties:
- </para>
+ </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>
- <listitem><para><emphasis>n</emphasis>: The number of incoming connections to wait for (in case of a n-of-m join).</para></listitem>
- </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, i.e. AND,
+ XOR or Discriminator (see above).</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>n</emphasis>: The number of incoming connections to
+ wait for (in case of a n-of-m join).</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>
+
+ <!-- EVENT WAIT -->
+ <listitem>
+ <para><emphasis role="strong">EventWait</emphasis>
+ (or <emphasis role="strong">Milestone</emphasis>):
+ Represents a wait state. An EventWait should have one incoming connection
+ and one outgoing connection. It specifies a constraint which defines how
+ long the process should wait in this state before continuing. For example,
+ a constraint in an order entry application might specify that the process
+ should wait until no more errors are found in the given order. Constraints
+ are specified using the same syntax as the left-hand side of a rule. When
+ a Wait node is reached in the ruleflow, the engine will check the associated
+ constraint. If the constraint evaluates to true directly, the flow will
+ continue imediately. Otherwise, the flow will continue if the constraint
+ is satisfied later on, for example when a fact is inserted, updated or
+ removed from the working memory. It contains the following properties:</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>
+ <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>
+
+ <!-- SUBPROCESS -->
+ <listitem>
+ <para><emphasis role="strong">SubFlow</emphasis>: represents the invocation
+ of another process from within this process. A sub-process node should
+ have one incoming connection and one outgoing connection. When a SubFlow
+ node is reached in the ruleflow, the engine will start the process with the
+ given id. It contains the following properties:</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>
+ <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 subprocess.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Independent</emphasis>: If this property is true, the
+ subprocess is started as an independent process, which means that the
+ SubFlow process will not be terminated if this process reaches an end node;
+ otherwise the active sub-process will be cancelled on termination (or abortion)
+ of the process.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>On-entry and on-exit actions</emphasis>: Actions that are
+ executed upon entry or exit of this node, respectively.</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 variable names given in the "in" mapping will be used
+ as parameters (with the associated parameter name) when starting the process.
+ The value of the variables in the subprocess with the given variable name
+ in the "out" mappings will be copied to the variables of this process when the
+ subprocess has been completed. Note that you can use "out" mappings only when
+ "Wait for completion" is set to true.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Timers</emphasis>: Timers that are linked to this node.
+ See section
+ <quote><link linkend='sec.timers' endterm="sec.timers.title"/></quote>
+ for 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>
+
+ <!-- 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, the dialect used for coding the action (i.e., Java or MVEL),
+ and the actual action code. This code can access any globals, the predefined
+ variable <code>drools</code> referring to a <code>KnowledgeHelper</code> object
+ (which can, for example,
+ be used to retrieve the Working Memory by calling
+ <code>drools.getWorkingMemory()</code>), and the variable <code>context</code>
+ that references the <code>ProcessContext</code> object (which can,
+ for example, be used to access the current <code>ProcessInstance</code> or
+ <code>NodeInstance</code>, and to get and set variables). When an Action node
+ is reached in the ruleflow, it will execute the action and then continue with the
+ next node. It contains the following properties:</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>
+ <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). Check out the section on timers to find out more information. The timer node contains the following properties:</para>
+
+ <!-- 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 timer period specifies the time between two
+ subsequent triggers. A period of 0 means that the timer should only be
+ triggered once. When a Timer node is reached in the ruleflow, it will
+ start the associated timer. The timer is cancelled if the timer node is
+ cancelled (e.g., by completing or aborting the process). Consult the
+ section <quote><link linkend='sec.timers' endterm="sec.timers.title"/></quote>
+ for more information. - The Timer 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>: T <programlisting>
- rule 'YourRule'
- ruleflow-group 'group1'
- when
- ...
- then
- ...
- end
- </programlisting>
-he 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>
+ <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>
+ <!-- FAULT -->
+ <listitem>
+ <para><emphasis role="strong">Fault</emphasis>: A Fault node can be used
+ to signal an exceptional condition in the process. It should
+ have one incoming connection and no outgoing connections. When a Fault
+ node is reached in the ruleflow, it will throw a fault with the given name.
+ The process will search for an appropriate exception handler that is
+ capable of handling this kind of fault. If no fault handler is found,
+ the process instance will be aborted. A Fault node contains the following
+ properties:</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>
+ <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>
+
+ <!-- EVENT -->
+ <listitem>
+ <para><emphasis role="strong">Event</emphasis>: An Event node can be used
+ to respond to internal or external events during the execution of the process.
+ An Event node should have no incoming connections and one outgoing
+ connection. It specifies the type of event that is expected. Whenever
+ that type of event is detected, the node connected to this Event node will
+ be triggered. It contains the following properties:</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>
+ <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
+ <code>processInstance.signalEvent(String type, Object data)</code>.
+ 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 <code>workingMemory.signalEvent(String type, Object event)</code>.</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 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>
+
+ <!-- HUMAN TASK -->
+ <listitem>
+ <para><emphasis role="strong">Human Task</emphasis>: Processes can also
+ involve tasks that need to be executed by human actors. A Human Task node
+ represents an atomic task to be executed by a human actor. It
+ should have one incoming connection and one outgoing connection.
+ Human Task nodes can be used in combination with Swimlanes to assign multiple
+ human tasks to similar actors. Refer to chapter
+ <quote><link linkend='ch.Human_Tasks' endterm="ch.Human_Tasks.title"/></quote>
+ for more details. A Human Task node is actually nothing more than a specific
+ type of work item node (of type "Human Task"). A Human Task node contains
+ the following properties:</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>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. 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>
+ <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., whether the actor may decide not to execute the
+ 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., by completing or reaching any other terminal state);
+ otherwise it will continue immediately after creating the human task.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>On.entry and on-exit actions</emphasis>: Actions that are
+ executed upon entry and exit of this node, respectively.</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
+ you can use result mappings only when "Wait for completion" is set to
+ true. A human task has a result variable "Result" that contains
+ the data returned by the human actor. The variable "ActorId" contains
+ the id of the actor that actually executed the task.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Timers</emphasis>: Timers that are linked to this
+ node. Consult the section
+ <quote><link linkend='sec.timers' endterm="sec.timers.title"/></quote>
+ for 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>
+
+ <!-- COMPOSITE -->
+ <listitem>
+ <para><emphasis role="strong">Composite</emphasis>: A Composite node is
+ a node that can contain other nodes so that it acts as a node container.
+ This allows not only the embedding of a part of the flow within such
+ a Composite node, but also the definition of additional variables and
+ exception handlers that are accessible for all nodes inside this
+ container. A Composite node should have one incoming connection and one
+ outgoing connection. It contains the following properties:</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>
+ <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 (within
+ this node container) that should be triggered when this node is
+ triggered.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>EndNodeId</emphasis>: The id of the node (within
+ this node container) that represents the end of the flow contained
+ in this node. When this node is completed, the composite node will
+ also be completed and trigger its outgoing connection. All other
+ executing nodes within this composite node will be cancelled.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Variables</emphasis>: Additional variables can be
+ defined to store data during the execution of this node. See section
+ <quote><link linkend='sec.data' endterm="sec.data.title"/></quote>
+ for details.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Exception Handlers</emphasis>: Specify the behavior
+ when a fault occurs in this node container. See section
+ <quote><link linkend='sec.exceptions' endterm="sec.exceptions.title"/></quote>
+ for 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>
+
+ <!-- FOR EACH -->
+ <listitem>
+ <para><emphasis role="strong">ForEach</emphasis>: A ForEach node is a
+ special kind of composite node that allows you to execute the contained
+ flow multiple times, once for each element in a collection. A ForEach
+ node should have one incoming connection and one outgoing connection. A
+ ForEach node awaits the completion of the embedded flow for each of the
+ collection''s elements before continuing. It contains the following
+ properties:</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>
+ <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 (within
+ 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 (within
+ this node container) that represents the end of the flow contained
+ in this node. When this node is completed, the execution of the
+ ForEach node will also be completed for the current collection element.
+ The outgoing connection is triggered if the collection is exhausted.
+ All other executing nodes within this composite node will be cancelled.</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
+ <code>java.util.Collection</code>.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>VariableName</emphasis>: The name of the variable
+ to contain the current element from the collection. This
+ gives nodes within the composite node access to the selected
+ element.</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>
+
+ <!-- WORK ITEMS -->
+ <listitem>
+ <para><emphasis role="strong">WorkItem</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 WorkItem node. Different types of work items are predefined, e.g.,
+ sending an email, logging a message, etc. Users can define domain-specific
+ work items, using a unique name and by defining
+ the parameters (input) and results (output) that are associated with this
+ type of work. Refer to the chapter
+ <quote><link linkend='ch.Domain_Specific_Processes'
+ endterm="ch.Domain_Specific_Processes.title"/></quote> for a
+ detailed explanation and illustrative examples of how to define and use
+ work items in your processes. When a WorkItem node is reached in the
+ process, the associated work item is executed. A WorkItem node should
+ have one incoming connection and one outgoing connection.</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 #{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>
+ <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 (completed or aborted)
+ its execution; 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 within the result parameter <code>Files</code>. This list
+ of files can then be bound to a process variable for use within the
+ process. Upon completion of the work item, the values will be copied.
+ Note that you can use result mappings only when "Wait for completion"
+ is set to true.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>On-entry and on-exit actions</emphasis>: Actions that are
+ executed upon entry or exit of this node, respectively.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Timers</emphasis>: Timers that are linked to this
+ node. See the section
+ <quote><link linkend='sec.timers' endterm="sec.timers.title"/></quote>
+ for 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 such as <code>From</code>, <code>To</code>, <code>Subject</code>
+ and <code>Body</code>. The user can either provide values for these
+ parameters directly, or define a
+ parameter mapping that will copy the value of the given variable
+ in this process to the given parameter; if both are specified, the
+ mapping will have precedence. Parameters of type <code>String</code> can use
+ <code>#{<emphasis>expression</emphasis>}</code> to embed a value in the
+ string. The value will be retrieved when creating the work item, and the
+ substitution expression will be replaced by the result of calling
+ <code>toString()</code> on the variable. The expression could
+ simply be the name of a variable (in which case it resolves
+ to the value of the variable), but more advanced MVEL expressions
+ are possible as well, e.g., <code>#{person.name.firstname}</code>.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
- </orderedlist>
- </para>
+ </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>
+ <section id='sec.data'>
+ <title id='sec.data.title'>Data</title>
- <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
+ <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. Throughout the execution of a process, data can retrieved,
+ stored, passed on and used.</para>
+
+ <para>For storing runtime data, during the execution of the process,
+ you use variables. A variable is defined by a name and a data type. This
+ could be a basic data type, such as boolean, int, or String, or any kind of
+ Object subclass. Variables can be defined inside a variable
+ <emphasis>scope</emphasis>. The top-level
+ scope is the variable scope of the process itself. Subscopes can be
+ defined using a Composite node. Variables that are defined in a subscope
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>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, and so on, until the process instance itself is reached.
+ If the variable cannot be found, a read access yields null, and a write
+ access produces an error message, with the process continuing its
+ execution.</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 access variables directly (by simply using the name of the variable as a parameter name).
- <programlisting>person.setAge(10); // with "person" a variable in the process</programlisting>
- Changing the value of a variable can be done through the knowledge context:
- <programlisting>kcontext.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 #{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>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>
+ <itemizedlist>
+ <listitem>Process-level variables can be set when starting a process
+ by providing a map of parameters to the invocation of the
+ <code>startProcess</code> method. These parameters will be set as
+ variables on the process scope.
+ </listitem>
+ <listitem>Actions can access variables directly, simply by using the
+ name of the variable as a parameter name.
+ <programlisting>
+// call method on the process variable "person"
+person.setAge(10);</programlisting>
+ Changing the value of a variable can be done through the Knowledge Context:
+ <programlisting>
+kcontext.setVariable(variableName, value);</programlisting>
+ </listitem>
+ <listitem>WorkItem and SubFlow nodes can pass the value of parameters
+ to the outside world by mapping the variable to one of the work item
+ parameters, either by using a parameter mapping or by interpolating
+ it into a String parameter, using
+ <code>#{<emphasis>expression</emphasis>}</code>. The results of a WorkItem
+ can also be copied to a variable using a result mapping.
+ </listitem>
+ <listitem>Various other nodes can also access data. Event nodes, for
+ example, 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>
</para>
- <para>Finally, processes and rules all have access to globals (globally defined variables that are considered immutable
- with regard to rule evaluation) and data in the knowledge session. The knowledge session can be accessed in actions
- using the knowledge context:</para>
- <programlisting>kcontext.getKnowledgeRuntime().insert( new Person("..") );</programlisting>
-
+ <para>Finally, processes and rules all have access to globals, i.e.,
+ globally defined variables that are considered immutable with regard
+ to rule evaluation, and data in the Knowledge Session. The Knowledge Session
+ can be accessed in actions using the Knowledge Context:</para>
+ <programlisting>
+kcontext.getKnowledgeRuntime().insert( new Person(...) );</programlisting>
+
</section>
- <section>
+ <section>
<title>Constraints</title>
- <para>Constraints can be used in various locations in your processes, like for example decision points (i.e. an (X)OR split), wait constraints, etc. Drools Flow supports two types of constraints:
- <itemizedlist>
- <listitem>code: Code constraints are expressions that return a boolean value. They are evaluated directly whenever they are reached. We currently support two dialects for expressing these code constraints: java and MVEL. Both java and MVEL code constraints have direct access to the globals and variables defined in the process. An example of a valid java code constraint would for example be (with person a variable in the process):
- <programlisting>return person.getAge() > 20;</programlisting>
-An similar example of a valid MVEL code constraint would be:
- <programlisting>return person.age > 20;</programlisting>
+ <para>Constraints can be used in various locations in your processes,
+ for example in a Split node using OR or XOR decisions, or as a
+ constraint for an EventWait. Drools Flow supports two types of constraints:
+ <itemizedlist>
+ <listitem><emphasis>Code constraints</emphasis> are boolean expressions,
+ evaluated directly whenever they are reached. We currently support two
+ dialects for expressing these code constraints: Java and MVEL.
+ Both Java and MVEL code constraints have direct access
+ to the globals and variables defined in the process. Here is an example
+ of a valid Java code constraint, <code>person</code> being a variable
+ in the process:
+ <programlisting>
+return person.getAge() > 20;</programlisting>
+A similar example of a valid MVEL code constraint is:
+ <programlisting>
+return person.age > 20;</programlisting>
</listitem>
- <listitem>rule: Rule constraints are equals to normal Drools rule conditions. They use the Drools Rule Language syntax to express possibly complex constraints. These rules can (like any other rule) refer to data in the working memory. They can also refer to globals directly. An example of a valid rule constraint would for example be:
- <programlisting>Person( age > 20 )</programlisting>
-which will search for a person older than 20 in the working memory.</listitem>
+ <listitem><emphasis>Rule constraints</emphasis> are equals to normal
+ Drools rule conditions. They use the Drools Rule Language syntax to
+ express possibly complex constraints. These rules can, like any other
+ rule, refer to data in the Working Memory. They can also refer to
+ globals directly. Here is an example of a valid rule constraint:
+ <programlisting
+>Person( age > 20 )</programlisting>
+ This tests for a person older than 20 being in the Working
+ Memory.</listitem>
</itemizedlist>
</para>
- <para>Rule constraints do not have direct access to variables defined inside the process. It is however possible to refer to the current process instance inside a rule constraint, by adding the process instance to the working memory and matching to the process instance inside your rule constraint. We have added special logic to make sure that a variable "processInstance" of type WorkflowProcessInstance will only match to the current process instance and not to other process instances in the working memory. Note that you are however responsible yourself to insert (and possibly update) the process instance into the session (for example using Java code or an (on-entry or on-exit or explicit) action in your process). The following exampleof a rule constraint will search for a person with the same name as the value stored in the variable "name" of the process:</para>
+ <para>Rule constraints do not have direct access to variables defined
+ inside the process. It is however possible to refer to the current process
+ instance inside a rule constraint, by adding the process instance to the
+ Working Memory and matching for the process instance in your rule
+ constraint. We have added special logic to make sure that a variable
+ <code>processInstance</code> of type <code>WorkflowProcessInstance</code>
+ will only match to the current process instance and not to other process
+ instances in the Working Memory. Note that you are however responsible
+ yourself to insert the process instance into the session and, possibly,
+ to update it, for example, using Java code or an on-entry or on-exit or
+ explicit action in your process. The following example of a rule
+ constraint will search for a person with the same name as the value
+ stored in the variable "name" of the process:</para>
- <programlisting>processInstance: WorkflowProcessInstance()
+ <programlisting>processInstance : WorkflowProcessInstance()
Person( name == ( processInstance.getVariable("name") ) )
# add more constraints here ...</programlisting>
</section>
- <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>
+ <listitem>Within an Action node,</listitem>
+ <listitem>As entry or exit actions, with a number of nodes,</listitem>
+ <listitem>Actions specifying the behavior of exception handlers.</listitem>
</itemizedlist>
</para>
- <para>Actions have access to globals and the variables that are defined 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, 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>
+ <para>Actions have access to globals and the variables that are defined
+ for the process and the predefined variable <code>context</code>. This
+ variable is of type
+ <code>org.drools.runtime.process.ProcessContext</code> and can be used for
+ several tasks:
+ <itemizedlist>
+ <listitem>Getting the current node instance (if applicable). The node
+ instance could be queried for data, such as its name and type. You can
+ also cancel the current node instance.
+ <programlisting>
+NodeInstance node = context.getNodeInstance();
+String name = node.getNodeName();</programlisting>
+ </listitem>
+ <listitem>Getting the current process instance. A process instance
+ can be queried for data (name, id, processId, etc.), aborted or
+ signalled an internal event.
+ <programlisting>
+WorkflowProcessInstance proc = context.getProcessInstance();
+proc.signalEvent( type, eventObject );</programlisting>
+ </listitem>
+ <listitem>Getting or setting the value of variables.</listitem>
+ <listitem>Accessing the Knowledge Runtime allows you do things
+ like starting a process, signalling external events, inserting data,
+ etc.</listitem>
</itemizedlist>
</para>
- <para>Drools currently supports two dialects: the java and the MVEL dialect. Java actions should be valid Java code. MVEL actions can use the business scripting language MVEL to express the action. MVEL accepts any valid Java code but also provides aditional support for nested accesses of parameters (e.g. person.name instead of person.getName()), and many other scripting improvements. Therefore, MVEL usually allows more business user friendly action expressions. For example, an action that prints out the name of the person in the "requester" variable of the process would look like this:</para>
+ <para>Drools currently supports two dialects, Java and MVEL.
+ Java actions should be valid Java code. MVEL actions can use the business
+ scripting language MVEL to express the action. MVEL accepts any valid Java
+ code but additionally provides support for nested accesses of parameters
+ (e.g., <code>person.name</code> instead of <code>person.getName()</code>),
+ and many other scripting improvements. Thus, MVEL expressions are more
+ convenient for the business user. For example, an action that prints out
+ the name of the person in the "requester" variable of the process would
+ look like this:</para>
- <programlisting>// using the Java dialect
+ <programlisting>
+// Java dialect
System.out.println( person.getName() );
-// Similarly, using the MVEL dialect
+// MVEL dialect
System.out.println( person.name );
</programlisting>
</section>
-
- <section>
- <title>Events</title>
-
- <figure>
- <title>A sample process using events</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Flow/EventProcess.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
+
+ <section>
+ <title>Events</title>
+
+ <figure>
+ <title>A sample process using events</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/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>
+ events in a process allows the process author to specify how the process should react
+ to such events.</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>Events have a type and possibly data associated with them. Users are free to define
+ their own event types and their associated data.</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>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
+ the name of a variable, which will receive the data that is associated with the event.
+ 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>
+ <itemizedlist>
+ <listitem>Internal event: Any action inside a process (e.g., the action of an
+ action node, or an on-entry or on-exit action of some node) can signal the
+ occurence of an internal event to the surrounding process instance, using code
+ like the following:
+ <programlisting>
+context.getProcessInstance().signalEvent(type, eventData);</programlisting></listitem>
+ <listitem>External event: A process instance can be notified of an event
+ from outside using code such as:
+ <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 <emphasis>event correlation</emphasis>, which is based
+ on the event type. A process instance that contains an event node
+ listening to external events of some type is notified whenever such
+ an event occurs. To signal such an event to the process engine, write
+ code such as:
+ <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>
-
+ <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="images/Chapter-Flow/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
+
+ <section id="sec.exceptions">
+ <title id="sec.exceptions.title">Exceptions</title>
+
+ <figure>
+ <title>A sample process using exception handlers</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/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>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, together with their data.</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>Faults are effected by a Fault node, generating a fault of the
+ given type, indicated by 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>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,
+ and so on, 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 can also specify a fault variable. The data
+ associated with the fault (if any) will be copied to this variable
+ whenever an exception handler is selected to handle a fault. This
+ allows subsequent Action 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>Exception handlers need to define an action that specifies how
+ to respond to the given fault. In most cases, the behavior that is
+ needed to react to the given fault cannot be expressed 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>
+
+ <section id="sec.timers">
+ <title id="sec.timers.title">Timers</title>
- <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>Timers wait for a predefined amount of time, before triggering, once
+ or repeatedly. They cou be used to specify time supervision, or to trigger
+ certain logic after a certain period, or to repeat some action at regular
+ intervals.</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>A Timer node is set up with a delay and a period. The delay specifies
+ the amount of time (in milliseconds) to wait after node activation before
+ triggering the timer the first time. The period defines the time between
+ subsequent trigger activations. A period of 0 results in a one-shot timer.</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>
+ <listitem>A Timer node may be added to the process flow. Its activation
+ starts the timer, and its triggers, once or repeatedly, activate the
+ Timer node's successor. This means that the outgoing connection of a
+ timer with a positive perios is triggered multiple times. Cancelling a
+ Timer node also cancels the associated timer, whereafter no more triggerings
+ will occur.</listitem>
+ <listitem>Timers may be associated with event-based nodes like WorkItem,
+ SubFlow, etc. A timer associated with a node is activated whenever
+ the node becomes active. The associated action is executed whenever
+ the timer triggers. You may use this, for instance, to send out
+ notifications, at regular intervals, when the execution of a task takes
+ too long, or to signal an event or a fault in case a time supervision
+ expires. When the node owning the timer completes, the timer is
+ automatically cancelled.</listitem>
</itemizedlist>
</para>
- <para>By default, the Drools engine is a passive component, meaning that it will only
- start processing if you tell it to (for example, you first insert the necessary data and then
- tell the engine to start processing). In passive mode, a timer that has been triggered will
- be put on the action queue. This means that it will be executed the next time the engine is
- told to start executing by the user (using fireAllRules() or if the engine is already / still
- running), in which case the timer will be executed automatically.</para>
+ <para>By default, the Drools engine is a passive component, meaning that
+ it will start processing only if you tell it to. Typically, you first
+ insert the necessary data and then tell the engine to start processing.
+ In passive mode, a timer that has been triggered will be put on the
+ action queue. This means that it will either be executed automatically
+ if the engine is still running, or it will become delayed until the engine
+ is told to start executing by the user (by calling
+ <code>fireAllRules()</code>).</para>
- <para>When using timers, it does usually make sense to make the Drools engine an active component,
- meaning that it will execute actions whenever they become available (and not wait until the user
- tells it to start executing again). This would mean a timer would be executed once it is triggered.
- To make the engine fire all actions continuously, you must call the fireUntilHalt() method. That
- means the engine will continue firing until the engine is halted. The following fragment shows
- how to do this (note that you should call fireUntilHalt() in a separate thread as it will only return
- if the engine has been halted (by either the user or some logic calling halt() on the session):</para>
+ <para>When using timers, it does usually make sense to let the Drools
+ engine operate as an active component, so that it will execute actions
+ whenever they become available, without the need to wait until the user
+ tells it to resume execution. Thus, a timer would become effective as
+ soon as it triggers. To make the engine fire all actions continuously,
+ you must call the method <code>fireUntilHalt()</code>, whereupon the
+ engine operates until <code>halt()</code> is called. Note that you should call
+ <code>fireUntilHalt()</code> in a separate thread as it will only
+ return if the engine has been halted, either by the user or some some
+ logic calling <code>halt()</code> on the session. The following
+ code snippet shows how to do this.</para>
<programlisting>
new Thread(new Runnable() {
@@ -875,190 +1469,186 @@
// starting a new process instance
ksession.startProcess("...");
-// any timer that will trigger will now be executed automatically</programlisting>
+// any timer that triggers will now be executed automatically</programlisting>
</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
- which rules are evaluated might become complex. Ruleflow allows you to
- specify the order in which rule sets should be evaluated by using a flow
- chart. This allows you to define which rule sets should be evaluated in
- sequence or in parallel, to specify conditions under which rule sets should
- be evaluated, etc. This chapter contains a few ruleflow examples.</para>
-
- <para>A rule flow is a graphical description of a sequence of steps that the
- rule engine needs to take, where the order is important. The ruleflow can
- also deal with conditional branching, parallelism, synchonization, etc.</para>
-
- <para>To use a ruleflow to describe the order in which rules should be
- evaluatied, you should first group rules into rulefow-groups using the ruleflow-group
- rule attribute ("options" in the GUI). Then you should create a ruleflow
- graph (which is a flow chart) that graphically describe the order in which the rules
- should be considered (by specifying the order in which the ruleflow-groups should
- be evaluated).</para>
-
- <programlisting>
- rule 'YourRule'
- ruleflow-group 'group1'
- when
- ...
- then
- ...
- end
- </programlisting>
-
- <para>This rule will then be placed in the ruleflow-group called "group1".</para>
- </section>
-
- <section>
- <title>A simple ruleflow</title>
-
- <figure>
- <title>Ruleflow</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Flow/RuleFlowSimple.png" format="PNG"
- role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The above rule flow specifies that the rules in the group "Check Order" must be
- executed before the rules in the group "Process Order". This means that only
- rules which are marked as having a ruleflow-group of "Check Order" will be
- considered first, and then "Process Order". That's about it. You could
- achieve similar results with either using salience (setting priorities, but this
- 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.</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
- "Split" and "Join" items from the component pallette. You use connections
- to connect from the start to ruleflow groups, or to Splits, and from
- splits to groups, joins etc. (i.e. basically like a simple flow chart that
- models your processing). You can work entirely graphically until you get
- the graph approximately right.</para>
-
- <figure>
- <title>Complex ruleflow</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Flow/RFComplex.png" format="PNG"
- role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The above flow is a more complex example. This example is an
- insurance claim processing rule flow. A description: Initially the claim
- data validation rules are processed (these check for data integrity and
- consistency, that all the information is there). Next there is a decision
- "split" - based on a condition which the rule flow checks (the value of
- the claim), it will either move on to an "auto-settlement" group, or to
- another "split", which checks if there was a fatality in the claim. If
- there was a fatality then it determines if the "regular" of fatality
- specific rules will take effect. And so on. What you can see from this is
- based on a few conditions in the rule flow the steps that the processing
- takes can be very different. Note that all the rules can be in one package
- - making maintenance easy. You can separate out the flow control from the
- actual rules.</para>
-
- <figure>
- <title>Split types</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Flow/RFSplitType.png" format="PNG"
- role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <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 (i.e. processing can
- proceed in parallel down more then one path). If you chose XOR, then it
- will be only one path.</para>
-
- <para>If you choose OR or XOR, then in the row that has constraints, you
- will see a button on the right hand side that has "..." - click on this,
- and you will see the constraint editor. From this constraint editor, you
- set the conditions which the split will use to decide which "output path"
- will be chosen.</para>
-
- <figure>
- <title>Edit constraints</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Flow/RFEditConstraints.png"
- format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Choose the output path you want to set the constraints for (eg
- Autosettlement), and then you should see the following constraint
- editor:</para>
-
- <figure>
- <title>Constraint editor</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Flow/RFConstraintEditor.png"
- format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>This is a text editor where the constraints (which are like the
- condition part of a rule) are entered. These constraints operate on facts
- in the working memory (eg. in the above example, it is checking for claims
- with a value of less than 250). Should this condition be true, then the
- path specified by it will be followed.</para>
+
+ <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 potentially many large rule-sets, managing the order in
+ which rules are evaluated might become complex. Ruleflow allows you to
+ specify the order in which rule sets should be evaluated by using a flow
+ chart. This allows you to define which rule sets should be evaluated in
+ sequence or in parallel, to specify conditions under which rule sets should
+ be evaluated. This chapter contains a few ruleflow examples.</para>
+
+ <para>A ruleflow is a graphical description of a sequence of steps that the
+ rule engine needs to take, where the order is important. The ruleflow can
+ also deal with conditional branching, parallelism, and synchonization.</para>
+
+ <para>To use a ruleflow to describe the order in which rules should be
+ evaluated, you should first group rules into ruleflow groups using the
+ <kw>ruleflow-group</kw> rule attribute ("options" in the GUI). Then you
+ should create a ruleflow graph (which is a flow chart) that graphically
+ describe the order in which the rules should be considered, by specifying
+ the order in which the ruleflow-groups should be evaluated.</para>
+
+ <programlisting>
+rule 'YourRule'
+ ruleflow-group 'group1'
+when
+ ...
+then
+ ...
+end</programlisting>
+
+ <para>This rule belongs to the ruleflow-group called "group1".</para>
</section>
- <section>
- <title>Using old Drools 4.x RuleFlow processes</title>
+ <section>
+ <title>A Simple Ruleflow</title>
+ <figure>
+ <title>Ruleflow</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/RuleFlowSimple.png" format="PNG"
+ role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The above rule flow specifies that the rules in the group "Check Order" must be
+ executed before the rules in the group "Process Order". This means that first only
+ rules which are marked as having a ruleflow-group of "Check Order" will be
+ considered, and then, only if there aren't any more of those, the rules of
+ "Process Order". That's about it. You could achieve similar results with either
+ using salience, but this 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, in a layer on top of the rule structure, so that
+ managing more complex situations becomes much easier.</para>
+
+ <para>In practice, if you are using ruleflow, you will most likely be
+ doing more than setting a simple sequence of groups to progress though.
+ You'll use Split and Join nodes for modeling branches of processing, and
+ define the flows of control by connections, from the Start to ruleflow
+ groups, to Splits and then on to more groups, Joins, and so on. All this
+ is done in a grphic editor.</para>
+
+ <figure>
+ <title>Complex ruleflow</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Flow/RFComplex.png" format="PNG"
+ role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The above flow is a more complex example, representing the rule
+ flow for processing an insurance claim. Initially the claim
+ data validation rules are processed, checking for data integrity,
+ consistency and completeness. Next, in a Split node, there is a decision
+ based on a condition based on the value ofthe claim. Processing will
+ either move on to an "auto-settlement" group, or to another Split node,
+ which checks whether there was a fatality in the incident. If so, it
+ determines whether the "regular" of fatality specific rules should take
+ effect, with more processing to follow. Based on a few conditions, many
+ different control flows are possible. Note that all the rules can be in
+ one package, with the control flow definition being separated from the
+ actual rules.</para>
+
+ <figure>
+ <title>Split types</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-Flow/RFSplitType.png" format="PNG"
+ role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>To edit Split nodes you click on the node, which will show you
+ a properties panel as shown above. You then have to choose the type:
+ AND, OR, and XOR. If you choose OR, then any of the "outputs" of the
+ split can happen, so that processing can proceed, in parallel, along
+ two or more paths. If you chose XOR, then only one path is chosen.</para>
+
+ <para>If you choose OR or XOR, the "Constraints" row will have a
+ square button on the right hand side. Clickin on this button opens
+ the Constraint editor, where you set the conditions deciding which
+ outgoing path to follow.</para>
+
+ <figure>
+ <title>Edit constraints</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/RFEditConstraints.png"
+ format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Choose the output path you want to set the constraints for (e.g.
+ Autosettlement), and then you should see the following constraint
+ editor:</para>
+
+ <figure>
+ <title>Constraint editor</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Flow/RFConstraintEditor.png"
+ format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>This is a text editor where the constraints - which are like the
+ condition part of a rule - are entered. These constraints operate on facts
+ in the working memory. In the above example, there is a check for claims
+ with a value of less than 250. Should this condition be true, then the
+ associated path will be followed.</para>
+ </section>
+
+ <section>
+ <title>Using Drools 4.x RuleFlow Processes</title>
+
<para>The XML format that was used in Drools4 to store RuleFlow processes
- was an automatically generated XML file generated by XStream. As a result,
- it was hard to read by human actors and hard to maintain and extend. The
+ was generated automatically, using XStream. As a result, it was hard to
+ read by human readers and difficult to maintain and extend. The
new Drools Flow XML format has been created to simplify this. This however
means that, by default, old RuleFlow processes cannot simply be executed on
the Drools5 engine.</para>
- <para>We do however provide a RuleFlowMigrator that allows you to transform
+ <para>We do however provide a Rule Flow Migrator that allows you to transform
your old .rf file to the new format. It uses an XSLT transformation to
generate the new XML based on the old content. You can use this class to
manually transform your old processes to the new format once when upgrading
from Drools4.x to Drools5.x. You can however also let the KnowledgeBuilder
- to automatically upgrade your processes when to the new format when they are
- loaded into the knowledge base. While this requires a conversion every time
- the process is loaded into the knowledge base, it does however support a more
- seamless upgrade. To support this automatic upgrade, you need to set the
+ automatically upgrade your processes to the new format when they are
+ loaded into the Knowledge Base. While this requires a conversion every time
+ the process is loaded into the Knowledge Base, it does support a more
+ seamless upgrade. To enact this automatic upgrade you need to set the
"drools.ruleflow.port" system property to "true", for example by adding
- -Ddrools.ruleflow.port=true when starting your application or by calling
- System.setProperty("drools.ruleflow.port", "true");</para>
+ <code>-Ddrools.ruleflow.port=true</code> when starting your application,
+ or by calling <code>System.setProperty("drools.ruleflow.port", "true")</code>.</para>
<para>The Drools Eclipse plugin also automatically detects if an old RuleFlow
file is opened. At that point, it will automatically perform the conversion
- and show the result in the graphical editor. You then need to save this result
- (either in a new file or by overriding the old one) to persist the old process
+ and show the result in the graphical editor. You then need to save this result,
+ either in a new file or overwriting the old one, to retain the old process
in the new format. Note that the plugin does not support editing and saving
processes in the old Drools4.x format.</para>
- </section>
-
-
-</chapter>
+ </section>
+
+
+</chapter>
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-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-GettingStarted/Chapter-GettingStarted.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,23 +1,23 @@
-<?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>Getting Started</title>
- <para>This section describes how to get started with Drools Flow. It
- will guide you to create and execute your first Drools Flow process.</para>
-
- <section>
+<?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>Getting Started</title>
+ <para>This section describes how to get started with Drools Flow. It
+ will guide you to create and execute your first Drools Flow process.</para>
+
+ <section>
<title>Installation</title>
-
- <para>The best way to get started is to use the Drools Eclipse Plugin. This
- is a plugin for the Eclipse development environment that allows users to
+
+ <para>The best way to get started is to use the Drools Eclipse Plugin for
+ the Eclipse development environment. It allows users to
create, execute and debug Drools processes and rules. To get started with the
- plugin, you first need an Eclipse 3.4.x (as well as the Eclipse
- Graphical Editing Framework (GEF) plugin installed). Eclipse can be downloaded
+ plugin, you first need an installation of Eclipse 3.4.x including the Eclipse
+ Graphical Editing Framework (GEF). Eclipse can be downloaded
from the following link (if you do not know which version of eclipse you need,
simply choose the "Eclipse IDE for Java Developers", and this one already includes
the GEF plugin as well):</para>
@@ -38,272 +38,289 @@
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. If you cannot find the Drools perspective
+ Click the "Open Perspective" button in the top right corner of your Eclipse window,
+ 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>
+ of Eclipse (3.4.x)? Ensure that you have Eclipse GEF installed, by checking whether the
+ <filename>org.eclipse.gef_3.4.*.jar</filename> exists in the plugins directory in your
+ Eclipse root folder. Make sure that you have extracted the Drools Eclipse
+ plugin correctly, by checking whether the <filename>org.drools.eclipse_*.jar</filename>
+ exists in the plugins directory in your Eclipse root folder. If you cannot find the
+ problem, try contacting us, either on irc or on the user mailing list. More information
+ can be found on our homepage:</para>
<para><ulink url="http://www.jboss.org/drools/">http://www.jboss.org/drools/</ulink></para>
- </section>
-
- <section>
- <title>Creating your first process</title>
-
- <para>A new Drools project wizard can be used to set up an executable project that contains
+ </section>
+
+ <section>
+ <title>Creating Your First Process</title>
+
+ <para>The Drools project wizard can be used to set up an executable project that contains
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". [Note that the
+ will set up 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". (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>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-GettingStarted/project-wizard1.bmp"/>
- </imageobject>
- </mediaobject>
-
- <para>Give your project a name and click Next. In the following dialog you can select
- which elements are added to your project by default. Since we are creating a new process,
- deselect the first two check boxes and select the last two. This will generate a sample
- process and a Java class to execute this process.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-GettingStarted/project-wizard2.bmp"/>
- </imageobject>
- </mediaobject>
-
+ (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", then "New" followed by "Project ...", and in the Drools folder,
+ select "Drools Project". This should open the following dialog:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="BMP" role=""
+ fileref="images/Chapter-GettingStarted/project-wizard1.bmp"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>Give your project a name and click "Next". In the following dialog you can select
+ which elements are added to your project by default. Since we are creating a new process,
+ deselect the first two checkboxes and select the last two. This will generate a sample
+ process and a Java class to execute this process.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="BMP" role=""
+ fileref="images/Chapter-GettingStarted/project-wizard2.bmp"/>
+ </imageobject>
+ </mediaobject>
+
<para>If you have not yet set up a Drools runtime, you should do this now. A Drools runtime
is a collection of jars on your file system that represent one specific release of the Drools
project jars. To create a runtime, you must either point the IDE to the release of your choice,
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>
-
- <para>So if you have not yet set up a Drools runtime, click the Next button. The following dialog
- 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>
+ 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>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-GettingStarted/project-wizard3.bmp"/>
- </imageobject>
+ <para>Unless you have already set up a Drools runtime, click the "Next" button. The
+ following dialog, as displayed 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>
+ <imageobject>
+ <imagedata align="center" format="BMP" role=""
+ fileref="images/Chapter-GettingStarted/project-wizard3.bmp"/>
+ </imageobject>
</mediaobject>
- <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. "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 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
- wizard by clicking on the "Finish" button.
- </para>
+ <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. "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 stored and click the "OK" button. You will see the selected path
+ showing up in the previous dialog. As we're all done here, click the "OK" button.
+ You will see the newly created runtime shown 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 wizard by clicking on the "Finish" button.</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-GettingStarted/project-runtimes.bmp"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="BMP" role=""
+ fileref="images/Chapter-GettingStarted/project-runtimes.bmp"/>
+ </imageobject>
</mediaobject>
- <para>The end result should look like this and contains:</para>
- <orderedlist>
- <listitem>
- <para>ruleflow.rf : the process definition, which is a very simple process containing
- 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>
- <para>RuleFlowTest.java : a Java class that executes the process.</para>
- </listitem>
- <listitem>
- <para>The necessary libraries are automatically added to the project classpath as a
- Drools library.</para>
- </listitem>
- </orderedlist>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-GettingStarted/initial.bmp"/>
- </imageobject>
- </mediaobject>
-
- <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>
-
- <para>This process is a simple sequence of three nodes. The start node defines the start of the
- process. It is connected to an action node (called 'Hello' that simply prints out 'Hello World'
- to the standard output. You can see this by clicking on the Hello node and checking the action
- property in the properties view below. This node is then connected to an end node, signaling
- the end of the process.</para>
-
- <para>While it is probably easier to edit processes using the graphical editor, user can also
- modify the underlying XML directly. The XML for our sample process is shown below (note that we
- did not include the graphical information here for simplicity). The process element contains
- parameters like the name and id of the process, and consists of three main subsections: a header
- (where information like variables, globals and imports can be defined), the nodes and the
- connections.</para>
-
-<programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-<process xmlns="http://drools.org/drools-5.0/process"
- xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
- xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.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>
-
- </section>
-
- <section>
+ <para>The end result should look like this and contains:</para>
+ <orderedlist>
+ <listitem>
+ <para><filename>ruleflow.rf</filename>: the process definition, which is a very
+ simple process containing
+ 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>
+ <para><filename>RuleFlowTest.java</filename>: a Java class that executes the
+ process.</para>
+ </listitem>
+ <listitem>
+ <para>The necessary libraries are automatically added to the project classpath as a
+ Drools library.</para>
+ </listitem>
+ </orderedlist>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%" format="BMP" role=""
+ fileref="images/Chapter-GettingStarted/initial.bmp"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>By double-clicking the <filename>ruleflow.rf</filename> 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>
+
+ <para>This process is a simple sequence of three nodes. The Start node defines the start
+ of the process. It is connected to an Action node (called "Hello" that simply prints out
+ "Hello World" to the standard output. You can see this by clicking on the "Hello" node and
+ checking the action property in the Properties View below. This node is then connected to
+ an End node, signaling the end of the process.</para>
+
+ <para>While it is probably easier to edit processes using the graphical editor, users
+ can also modify the underlying XML directly. The XML for our sample process is shown
+ below (note that we did not include the graphical information here for simplicity).
+ The process element contains parameters like the name and id of the process, and consists
+ of three main subsections: a header (where information like variables, globals and
+ imports can be defined), the nodes and the connections.</para>
+
+<programlisting>
+<?xml version="1.0" encoding="UTF-8"?>
+<process xmlns="http://drools.org/drools-5.0/process"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
+ xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.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>
+
+ </section>
+
+ <section>
<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>
-<programlisting>
-Hello World
-</programlisting>
-
- <para>If you look at the RuleFlowTest code (see below), you will see that executing a process
- requires a few steps:</para>
- <orderedlist>
- <listitem>
- <para>You should first create a knowledge base. A knowledge base contains all the knowledge
- (i.e. processes, rules, etc.) that are relevant in your application. This knowledge base can be
- created only once and can be reused. In this case, the knowledge base only consists of our
- sample process.</para>
- </listitem>
- <listitem>
- <para>Next, you should create a session to interact with the engine. Note that we also add
- a logger to the session to log execution events and make it easier to visualize what is going
- on.</para>
- </listitem>
- <listitem>
- <para>Finally, you can start a new instance of the process by invoking the
- startProcess("processId") method on the session. This will start the execution of your
- process instance. The process instance will execute the start node, action node and end
- node in this order, after which the process instance will be completed.</para>
- </listitem>
- </orderedlist>
-
-<programlisting>
-package com.sample;
-
-import org.drools.KnowledgeBase;
-import org.drools.KnowledgeBaseFactory;
-import org.drools.builder.KnowledgeBuilder;
-import org.drools.builder.KnowledgeBuilderError;
-import org.drools.builder.KnowledgeBuilderErrors;
-import org.drools.builder.KnowledgeBuilderFactory;
-import org.drools.builder.KnowledgeType;
-import org.drools.io.ResourceFactory;
-import org.drools.logger.KnowledgeRuntimeLogger;
-import org.drools.logger.KnowledgeRuntimeLoggerFactory;
-import org.drools.runtime.StatefulKnowledgeSession;
-
-/**
- * This is a sample file to launch a process.
- */
-public class RuleFlowTest {
-
- public static final void main(String[] args) {
- try {
- // load up the knowledge base
- KnowledgeBase kbase = readKnowledgeBase();
- StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
- KnowledgeRuntimeLogger logger = KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "test");
- // start a new process instance
- ksession.startProcess("com.sample.ruleflow");
- logger.close();
- } catch (Throwable t) {
- t.printStackTrace();
- }
- }
-
- private static KnowledgeBase readKnowledgeBase() throws Exception {
- KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
- kbuilder.add(ResourceFactory.newClassPathResource("ruleflow.rf"), KnowledgeType.DRF);
- KnowledgeBuilderErrors errors = kbuilder.getErrors();
- if (errors.size() > 0) {
- for (KnowledgeBuilderError error: errors) {
- System.err.println(error);
- }
- throw new IllegalArgumentException("Could not parse knowledge.");
- }
- KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
- kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
- return kbase;
- }
-
-}
-</programlisting>
-
- <para>Congratulations, you have successfully executed your first process! Because we added a
- logger to the session, you can easily check what happened internally by looking at the audit
- log. Select the "Audit View" tab on the bottom right, next to the Console tab. Click on the
- "Open Log" button (the first one one the right of the view) and navigate to the newly created
- "test.log" file in your project folder (if you are not sure where this project folder is
- located, right-click on the project folder and you will find the location in the "Resource"
- section). An image like the one below should be shown. It is a tree view of the events that
- occurred at runtime. Events that were executed as the direct result of another event are shown
- as the child of that event. This log shows that after starting the process, the start node,
- the action node and the end node were triggered in that order, after which the process instance
- was completed.</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-GettingStarted/audit.bmp"/>
- </imageobject>
- </mediaobject>
-
- <para>You can now start experimenting and designing your own process by modifying our example.
- Note that you can validate your process by clicking on the "Check the ruleflow model" button
- (the green check box action in the upper toolbar that shows up if you are editing a process).
- Processes will also be validated upon save and errors will be shown in the error view. Or
- you can continue reading our documentation to learn about our more advanced features.</para>
-
- </section>
-
-</chapter>
+ <para>To execute this process, right-click on <filename>RuleFlowTest.java</filename>
+ and select "Run As..." and "Java Application". When the process in executed, the
+ following output should appear in the Console window:</para>
+<programlisting>
+Hello World
+</programlisting>
+
+ <para>If you look at the code of class <code>RuleFlowTest</code> (see below),
+ you will see that executing a process requires a few steps:</para>
+ <orderedlist>
+ <listitem>
+ <para>You should first create a Knowledge Base. A Knowledge Base contains
+ all the knowledge (i.e., processes, rules, etc.) that are relevant in your
+ application. This Knowledge Base is usually created once, and then reused.
+ In this case, the Knowledge Base only consists of our sample process.</para>
+ </listitem>
+ <listitem>
+ <para>Next, you should create a session to interact with the engine. Note
+ that we also add a logger to the session to log execution events and make
+ it easier to visualize what is going on.</para>
+ </listitem>
+ <listitem>
+ <para>Finally, you can start a new instance of the process by invoking the
+ <code>startProcess(String processId)</code> method on the session. This starts
+ the execution of your process instance, resulting in the executions of the
+ Start node, the Action node, and the End node, in this order, after which the
+ process instance will be completed.</para>
+ </listitem>
+ </orderedlist>
+
+<programlisting>
+package com.sample;
+
+import org.drools.KnowledgeBase;
+import org.drools.KnowledgeBaseFactory;
+import org.drools.builder.KnowledgeBuilder;
+import org.drools.builder.KnowledgeBuilderError;
+import org.drools.builder.KnowledgeBuilderErrors;
+import org.drools.builder.KnowledgeBuilderFactory;
+import org.drools.builder.KnowledgeType;
+import org.drools.io.ResourceFactory;
+import org.drools.logger.KnowledgeRuntimeLogger;
+import org.drools.logger.KnowledgeRuntimeLoggerFactory;
+import org.drools.runtime.StatefulKnowledgeSession;
+
+/**
+ * This is a sample file to launch a process.
+ */
+public class RuleFlowTest {
+
+ public static final void main(String[] args) {
+ try {
+ // load up the knowledge base
+ KnowledgeBase kbase = readKnowledgeBase();
+ StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
+ KnowledgeRuntimeLogger logger =
+ KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "test");
+ // start a new process instance
+ ksession.startProcess("com.sample.ruleflow");
+ logger.close();
+ } catch (Throwable t) {
+ t.printStackTrace();
+ }
+ }
+
+ private static KnowledgeBase readKnowledgeBase() throws Exception {
+ KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+ kbuilder.add(ResourceFactory.newClassPathResource("ruleflow.rf"), KnowledgeType.DRF);
+ KnowledgeBuilderErrors errors = kbuilder.getErrors();
+ if (errors.size() > 0) {
+ for (KnowledgeBuilderError error: errors) {
+ System.err.println(error);
+ }
+ throw new IllegalArgumentException("Could not parse knowledge.");
+ }
+ KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
+ return kbase;
+ }
+
+}
+</programlisting>
+
+ <para>Congratulations, you have successfully executed your first process!
+
+ Because we added a logger to the session, you can easily check what happened
+ internally by looking at the audit log. Select the "Audit View" tab on the
+ bottom right, next to the Console tab. Click on the "Open Log" button (the
+ first one one the right of the view) and navigate to the newly created
+ <filename>test.log</filename> file in your project folder. (If you are not
+ sure where this project folder is located, right-click on the project folder
+ and you will find the location in the "Resource" section). An image like the
+ one below should be shown. It is a tree view of the events that
+ occurred at runtime. Events that were executed as the direct result of another
+ event are shown as the children of that event. This log shows that after
+ starting the process, the Start node, the Action node and the End node were
+ triggered, in that order, after which the process instance was completed.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="BMP" role=""
+ fileref="images/Chapter-GettingStarted/audit.bmp"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>You can now start experimenting and designing your own process by
+ modifying our example. Note that you can validate your process by clicking
+ on the "Check the ruleflow model" button, i.e., the green check box action in
+ the upper toolbar that shows up if you are editing a process. Processes will
+ also be validated upon save, and errors will be shown in the Error View.</para>
+
+ <para>Continue reading our documentation to learn about our more advanced features.</para>
+
+ </section>
+
+</chapter>
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-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-HumanTasks/Chapter-HumanTasks.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,284 +1,348 @@
-<?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>Human Tasks</title>
-
- <para>An important aspect of work flow and BPM (business process management)is human task management.
- While some of the work performed in a process can be executed automatically, some tasks need to be executed
- with the interaction of human actors. Drools Flow supports the use of human tasks inside processes using a
- special human task node that will represent this interaction. 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>
- <listitem><emphasis>ParentId</emphasis>: Allows to specify the parent task id, in the case that this task is a sub task of another. (see the 'sub task' 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 scalefit="1" 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>
-
- <para>At this moment WSHumanTaskHandler is using Mina
- <ulink url="http://mina.apache.org/">(http://mina.apache.org/)</ulink> for testing the behavior in a client/server
- architecture. Mina uses messages between client and server to enable the
- client comunicate with the server. That's why WSHumanTaskHandler have a
- MinaTaskClient that create different messages to give the user different
- actions that are executed for the server.</para>
-
- <para>In the client (MinaTaskClient in this implementation) should see
- the implementation of the following methods to interact with Human
- Tasks:</para>
-
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="ch.Human_Tasks"
+ 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 id="ch.Human_Tasks.title">Human Tasks</title>
+
+ <para>An important aspect of work flow and BPM (business process
+ management)is human task management.
+ While some of the work performed in a process can be executed
+ automatically, some tasks need to be executed
+ with the interaction of human actors. Drools Flow supports the use
+ of human tasks inside processes using a
+ special human task node that will represent this interaction. 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 and on-exit actions</emphasis>: Actions that are executed
+ upon entry and 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>
+ <listitem><emphasis>ParentId</emphasis>: Allows to specify the parent task id, in
+ the case that this task is a sub task of another. (see the 'sub task' 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 scalefit="1" align="center" width="100%"
+ 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>
+
+ <para>At this moment WSHumanTaskHandler is using Mina
+ <ulink url="http://mina.apache.org/">(http://mina.apache.org/)</ulink> for
+ testing the behavior in a client/server
+ architecture. Mina uses messages between client and server to enable the
+ client comunicate with the server. That's why WSHumanTaskHandler have a
+ MinaTaskClient that create different messages to give the user different
+ actions that are executed for the server.</para>
+
+ <para>In the client (MinaTaskClient in this implementation) we should see
+ the implementation of the following methods for interacting with Human
+ Tasks:</para>
+
<para><programlisting>
-public void start(long taskId, String userId, TaskOperationResponseHandler responseHandler)
-public void stop(long taskId, String userId, TaskOperationResponseHandler responseHandler)
-public void release(long taskId, String userId, TaskOperationResponseHandler responseHandler)
-public void suspend(long taskId, String userId, TaskOperationResponseHandler responseHandler)
-public void resume(long taskId, String userId, TaskOperationResponseHandler responseHandler)
-public void skip(long taskId, String userId, TaskOperationResponseHandler responseHandler)
-public void delegate(long taskId, String userId, String targetUserId, TaskOperationResponseHandler responseHandler)
-public void complete(long taskId, String userId, ContentData outputData, TaskOperationResponseHandler responseHandler)
-...</programlisting></para>
-
- <para>Using this methods we will implement any kind of GUI that the end
- user will use to do the task that they have assigned. If you take a look
- a this method signatures you will notice that almost all of this method
- takes the following arguments:</para>
-
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">taskId<emphasis>:</emphasis>
- <emphasis>the id of the task with we are working. Probably you will
- pick this Id from the user task list in the UI (User
- Interface).</emphasis></emphasis></para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">userId</emphasis>: the id of the user
- that is executing the action. Probably the Id of the user that is
- signed in the application.</para>
- </listitem>
-
- <listitem>
- <para><emphasis role="bold">responseHandler</emphasis>: this is the
- handler have responsability to catch the response and get the
- results or just let us know that the task is already
- finished.</para>
- </listitem>
- </itemizedlist>
-
- <para>As you can imagine all the methods create a message that will be
- sended to the server, and the server will execute the logic that
- implement the correct action. A creation of one of this messages will be
- like this:</para>
-
+public void start( long taskId, String userId, TaskOperationResponseHandler responseHandler )
+public void stop( long taskId, String userId, TaskOperationResponseHandler responseHandler )
+public void release( long taskId, String userId, TaskOperationResponseHandler responseHandler )
+public void suspend( long taskId, String userId, TaskOperationResponseHandler responseHandler )
+public void resume( long taskId, String userId, TaskOperationResponseHandler responseHandler )
+public void skip( long taskId, String userId, TaskOperationResponseHandler responseHandler )
+public void delegate( long taskId, String userId, String targetUserId,
+ TaskOperationResponseHandler responseHandler )
+public void complete( long taskId, String userId, ContentData outputData,
+ TaskOperationResponseHandler responseHandler )
+...</programlisting></para>
+
+ <para>Using this methods we will implement any kind of GUI that the end
+ user will use to do the task that they have assigned. If you take a look
+ a this method signatures you will notice that almost all of this method
+ takes the following arguments:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">taskId</emphasis>:
+ the id of the task with we are working. Probably you will
+ pick this Id from the user task list in the UI (User
+ Interface).</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">userId</emphasis>: the id of the user
+ that is executing the action. Probably the Id of the user that is
+ signed in the application.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">responseHandler</emphasis>: this is the
+ handler have responsability to catch the response and get the
+ results or just let us know that the task is already
+ finished.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>As you can imagine all the methods create a message that will be
+ sended to the server, and the server will execute the logic that
+ implement the correct action. A creation of one of this messages will be
+ like this:</para>
+
<para><programlisting>
-public void complete(long taskId,
- String userId,
- ContentData outputData,
- TaskOperationResponseHandler responseHandler) {
- List<Object> args = new ArrayList<Object>( 5 );
- args.add( Operation.Complete );
- args.add( taskId );
- args.add( userId );
- args.add( null );
- args.add( outputData );
- Command cmd = new Command( counter.getAndIncrement(),
- CommandName.OperationRequest,
- args );
-
- handler.addResponseHandler( cmd.getId(),
- responseHandler );
- session.write( cmd );
+public void complete(long taskId,
+ String userId,
+ ContentData outputData,
+ TaskOperationResponseHandler responseHandler) {
+ List<Object> args = new ArrayList<Object>( 5 );
+ args.add( Operation.Complete );
+ args.add( taskId );
+ args.add( userId );
+ args.add( null );
+ args.add( outputData );
+ Command cmd = new Command( counter.getAndIncrement(),
+ CommandName.OperationRequest,
+ args );
+
+ handler.addResponseHandler( cmd.getId(),
+ responseHandler );
+ session.write( cmd );
}</programlisting>
- Here we can see that a Command is created and the arguments
- of the method are inserted inside the command with the type of operation
- that we are trying to execute and then this command is sended to the
- server with session.write( cmd ) method.</para>
-
- <para>If we see the server implementation, when the command is recived,
- we find that depends of the operation type (here Operation.Complete)
- will be the logic that will be executed. If we look at the class
- TaskServerHandler in the messageReceived method the taskOperation is
- executed using the taskServiceSession that is the responsible for get,
- persist and manipulate all the Human Task Information when the tasks are
- created and the user is not interacting with them.</para>
-
-
- </section>
-
- <section>
- <title>Starting the task management component</title>
-
+ Here we can see that a Command is created and the arguments
+ of the method are inserted inside the command with the type of operation
+ that we are trying to execute and then this command is sended to the
+ server with session.write( cmd ) method.</para>
+
+ <para>If we see the server implementation, when the command is recived,
+ we find that depends of the operation type (here Operation.Complete)
+ will be the logic that will be executed. If we look at the class
+ TaskServerHandler in the messageReceived method the taskOperation is
+ executed using the taskServiceSession that is the responsible for get,
+ persist and manipulate all the Human Task Information when the tasks are
+ created and the user is not interacting with them.</para>
+
+
+ </section>
+
+ <section>
+ <title>Starting the Task Management Component</title>
+
<para>The task management component is a completely independent service
that the process engine communicates with. We therefore recommend to
start it as a separate service as well. To start the task server, you
@@ -363,82 +427,87 @@
<para>The drools-process-task module contains a org.drools.task.RunTaskService
class in the src/test/java source folder that can be used to start a task server.
It automatically adds users and groups as defined in LoadUsers.mvel and
- LoadGroups.mvel configuration files.</para>
- </section>
-
- <section>
- <title>Interacting with the task management component</title>
-
- <para>The task management component exposes various methods to manage the life cycle of the tasks through a Java API.
- This allows clients to integrate (at a low level) with the task management component. Note that end users should probably
- not interact with this low-level API directly but rather use one of the task list clients. These clients interact with
- the task management component using this API.</para>
-
- <para>This interaction will be described with the following image:</para>
- <mediaobject>
- <imageobject>
- <imagedata scalefit="1" align="center" fileref="images/Chapter-HumanTasks/component-distribution.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
- <para>
- As we can see in the image we have MinaTaskClient and MinaTaskServer. They communicate to each other sending
- messages to query and manipulate human tasks. Step by step the interaction will be something like this:
- <itemizedlist>
- <listitem>
- <para>
- Some client need to complete some task. So he/she needs to create an instace of MinaTaskClient
- and connect it to the MinaTaskServer to have a session to talk to each other. This is the step one in the image.
- </para>
- </listitem>
- <listitem>
- <para>
- Then the client can call the method complete() in MinaTaskClient with the corresponding
- arguments. This will generate a new Message (or Command) that will be inserted in the session
- that the client open when it connects to the server. This message must specify a type that the
- server recognize and know what to do when the message is recieved. This is the step two in the image.
- </para>
- </listitem>
- <listitem>
- <para>
- At this moment TaskServerHandler noticed that there is a new message in the session so an analysis
- about what kind of message is will take place. In this case is the type of Operation.Complete, because
- the client is finishing succesfully some task. So we need to complete the task that the user want to finish.
- This is achieved using the TaskServiceSession that will fire an specific type of event that will be procesed by
- an specific subclass of TaskEventListener. This are step three and four in the image.
-
- </para>
- </listitem>
- <listitem>
- <para>
- When the event is recived by TaskEventListener it will know how to modify the status of the task. This is achieved
- using the EntityManager to retrieve and modify the status of an specific task from the database. In this case, because
- we are finishing a task, the status will be updated to Completed. This is step five in the image.
- </para>
- </listitem>
- <listitem>
- <para>
- Now, when the changes are made we need to notify the client about that the task was succesfully ended and
- this is achieved creating a response message that TaskClientHandler will receive and inform MinaTaskClient.
- This are steps six, seven and eight in the image.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
-
- </section>
-
- </section>
-
- <section>
- <title>Human task management interface</title>
-
- <para></para>
-
- <section>
- <title>Eclipse integration</title>
-
+ LoadGroups.mvel configuration files.</para>
+ </section>
+
+ <section>
+ <title>Interacting With the Task Management Component</title>
+
+ <para>The task management component exposes various methods to manage the
+ life cycle of the tasks through a Java API.
+ This allows clients to integrate (at a low level) with the task management
+ component. Note that end users should probably
+ not interact with this low-level API directly but rather use one of the
+ task list clients. These clients interact with
+ the task management component using this API.</para>
+
+ <para>This interaction will be described with the following image:</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata scalefit="1" align="center"
+ fileref="images/Chapter-HumanTasks/component-distribution.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ <para>As we can see in the image we have MinaTaskClient and MinaTaskServer.
+ They communicate to each other sending
+ messages to query and manipulate human tasks. Step by step the interactio
+ n will be something like this:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Some client need to complete some task. So he/she needs to
+ create an instace of MinaTaskClient
+ and connect it to the MinaTaskServer to have a session to talk to
+ each other. This is the step one in the image. </para>
+ </listitem>
+ <listitem>
+ <para>Then the client can call the method complete() in MinaTaskClient
+ with the corresponding
+ arguments. This will generate a new Message (or Command) that will
+ be inserted in the session
+ that the client open when it connects to the server. This message
+ must specify a type that the server recognize and know what to do
+ when the message is recieved. This is the step two in the image.</para>
+ </listitem>
+ <listitem>
+ <para>At this moment TaskServerHandler noticed that there is a new
+ message in the session so an analysis
+ about what kind of message is will take place. In this case is the
+ type of Operation.Complete, because
+ the client is finishing succesfully some task. So we need to complete
+ the task that the user want to finish.
+ This is achieved using the TaskServiceSession that will fire an
+ specific type of event that will be procesed by
+ an specific subclass of TaskEventListener. This are step three
+ and four in the image.</para>
+ </listitem>
+ <listitem>
+ <para>When the event is recived by TaskEventListener it will
+ know how to modify the status of the task. This is achieved
+ using the EntityManager to retrieve and modify the status of
+ an specific task from the database. In this case, because
+ we are finishing a task, the status will be updated to Completed.
+ This is step five in the image.</para>
+ </listitem>
+ <listitem>
+ <para>Now, when the changes are made we need to notify the
+ client about that the task was succesfully ended and
+ this is achieved creating a response message that TaskClientHandler
+ will receive and inform MinaTaskClient.
+ This are steps six, seven and eight in the image.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Human Task Management Interface</title>
+
+ <para></para>
+
+ <section>
+ <title>Eclipse integration</title>
+
<para>The Drools IDE contains a org.drools.eclipse.task plugin that allows you to test and/or debug
processes using human tasks. In contains a Human Task View that can connect to a running task
management component, request the relevant tasks for a particular user (i.e. the tasks where the user
@@ -447,52 +516,53 @@
stopping the execution of a task, completing a task, etc. A screenshot of this Human Task View is
shown below. You can configure which task management component to connect to in the Drools Task
preference page (select Window -> Preferences and select Drools Task). Here you can specify the
- url and port (default = 127.0.0.1:9123).</para>
+ url and port (default = 127.0.0.1:9123).</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-HumanTasks/human_task_view.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </section>
-
- <section>
- <title>Web-based task view</title>
-
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ fileref="images/Chapter-HumanTasks/human_task_view.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>Web-based Task View</title>
+
<para>We are targeting to add a web-based view that end users can use for managing their tasks
- for Drools 5.1.</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>
+ for Drools 5.1.</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>
Modified: 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 2009-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,20 +1,20 @@
-<?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"
+<?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
+ <para>Drools Flow allows the persistent storage of certain information,
+ i.e., the process runtime state, the process definitions and the
history information.</para>
- <section>
- <title>Runtime state</title>
+ <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,
@@ -23,60 +23,68 @@
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
+ process instance at some later time, but it 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>
+ needed in the process instance.</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>
+ <para>The runtime state of an executing process can be made persistent,
+ for example, in a database. This allows to restore the state of
+ execution of all running processes in case of unexpected failure,
+ or to temporarily remove running instances from memory 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 made persistent.</para>
<section>
- <title>Binary persistence</title>
+ <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 variable values.</para>
+ <para>Drools Flow provides a binary persistence mechanism that allows
+ you to save the state of a process instance as a binary dataset. This
+ way, the state of all running process instances can always be stored in
+ a persistent location. Note that these binary datasets 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., any node that is currently
+ executing, and, possibly, some variable values.</para>
</section>
<section>
- <title>Safe points</title>
+ <title>Safe Points</title>
- <para>The state of a process instance is stored at so-called "safe points" during the
- execution of the process engine. Whenever a process instance is executed (for example by
- starting it, or by continuing after receiving a trigger it was waiting for), the engine
- continues execution of 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
+ <para>The state of a process instance is stored at so-called "safe points"
+ during the execution of the process engine. Whenever a process instance
+ is executing, after its start or continuation from a wait state, the engine
+ proceeds 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>
- <title>Configuring persistence</title>
+ <title>Configuring Persistence</title>
- <para>By default, the engine does automatically persist the runtime data. It is however
- pretty straightforward to configure the engine to do this, by adding a config file and
- the necessary dependencies. The persistence itself is based on the Java Persistence API
- (JPA) and can thus work with several persistence mechanisms. We are using Hibernate by
- default (but feel free to check out other alternatives). We're using the H2 database
- underneath to store the data (but again you're free to choose your own alternative).</para>
+ <para>By default, the engine does not save runtime data persistently.
+ It is, however, pretty straightforward to configure the engine to do
+ this, by adding a configuration file and the necessary dependencies.
+ Persistence itself is based on the Java Persistence API (JPA) and can
+ thus work with several persistence mechanisms. We are using Hibernate by
+ default, but feel free to employ alternatives. A H2 database is used
+ underneath to store the data, but you mighto choose your own alternative
+ for this, too.</para>
- <para>First of all, you need to add the necessary dependencies to your classpath. If you're
- using the Eclipse IDE, you can do that by adding the jars to your Drools runtime directory
- (see the chapter on the Eclipse IDE), or by manually adding these dependencies to your project.
- First of all you need the drools-persistence-jpa jar, as that contains the necessary code
- to persist the runtime state whenever necessary. Next, you also need various other dependencies,
- but these are different depending on the persistence solution and database you are using. In
- our case (using Hibernate as the JPA persistence provider, the H2 database and bitronix for
- JTA-based transaction management), the following list of dependencies is needed:
+ <para>First of all, you need to add the necessary dependencies to your
+ classpath. If you're using the Eclipse IDE, you can do that by adding
+ the jar files to your Drools runtime directory (cf. chapter
+ <quote><link linkend='ch.Drools_Eclipse_IDE_Features'
+ endterm="ch.Drools_Eclipse_IDE_Features,title"/></quote>),
+ or by manually adding these dependencies to your project. First of all,
+ you need the jar file <filename>drools-persistence-jpa.jar</filename>,
+ as that contains code for saving the runtime state whenever necessary.
+ Next, you also need various other dependencies, depending on the
+ persistence solution and database you are using. For the default
+ combination with Hibernate as the JPA persistence provider, the H2
+ database and Bitronix for JTA-based transaction management, the
+ following list of dependencies is needed:
<orderedlist>
<listitem>drools-persistence-jpa (org.drools)</listitem>
<listitem>persistence-api-1.0.jar (javax.persistence)</listitem>
@@ -95,10 +103,12 @@
</orderedlist>
</para>
- <para>Next, you need to configure the Drools engine to persist the state of the engine whenever
- necessary. The easiest way to do this is to use the JPAKnowledgeService to create your knowledge
- session, based on a knowledge base, a knowledge session configuration (if necessary) and an
- environment. The environment needs to contain a reference to your entity manager factory.</para>
+ <para>Next, you need to configure the Drools engine to save the state of the
+ engine whenever necessary. The easiest way to do this is to use
+ <code>JPAKnowledgeService</code> to create your knowledge session, based on a
+ Knowledge Base, a Knowledge Session Configuration (if necessary) and an
+ environment. The environment needs to contain a reference to your
+ Entity Manager Factory.</para>
<programlisting>
// create the entity manager factory and register it in the environment
@@ -116,7 +126,8 @@
ksession.startProcess( "MyProcess" );
ksession.dispose();</programlisting>
- <para>You can also yse the JPAKnowledgeService to recreate a session based on a specific session id:</para>
+ <para>You can also yse the <code>JPAKnowledgeService</code> to recreate
+ a session based on a specific session id:</para>
<programlisting>
// recreate the session from database using the sessionId
@@ -139,17 +150,20 @@
drools.workItemManagerFactory = org.drools.persistence.processinstance.JPAWorkItemManagerFactory
drools.processSignalManagerFactory = org.drools.persistence.processinstance.JPASignalManagerFactory</programlisting-->
- <para>Note that we only persist the minimal state that is needed to continue execution of the process
- instance at some later point. This for example means that it does not contain information about already
- executed nodes if that information is no longer relevant, or that process instances that have been
- completed or aborted are removed from the database. If you however want to search for history-related
+ <para>Note that we only save the minimal state that is needed to continue
+ execution of the process instance at some later point. This means, for example, that
+ it does not contain information about already executed nodes if that information
+ is no longer relevant, or that process instances that have been completed or
+ aborted are removed from the database. If you want to search for history-related
information, you should use the history log, as explained later.</para>
- <para>By default, the drools-persistence-jpa jar contains a configuration file that configures
- JPA to use hibernate and the H2 database, called persistence.xml in the META-INF directory, as shown below.
- You will need to override these defaults if you want to change them, by adding your own persistence.xml in
- your classpath (before the default one in the drools-persistence-jpa jar). We refer to the JPA and Hibernate
- documentation for more information on how to do this.</para>
+ <para>By default, <filename>drools-persistence-jpa.jar</filename> contains a configuration
+ file that configures JPA to use Hibernate and the H2 database, called
+ <filename>persistence.xml</filename> in the META-INF directory, as shown below.
+ You will need to override these defaults if you want to change them, by adding
+ your own <filename>persistence.xml</filename> in your classpath, preceding the
+ default one in <filename>drools-persistence-jpa.jar</filename>. Refer to
+ the JPA and Hibernate documentation for more information on how to do this.</para>
<programlisting>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
@@ -158,7 +172,7 @@
xsi:schemaLocation=
"http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd
- http://java.sun.com/xml/ns/persistence/orm
+ http://java.sun.com/xml/ns/persistence/orm
http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -173,19 +187,19 @@
<class>org.drools.persistence.processinstance.WorkItemInfo</class>
<properties>
- <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
+ <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
<property name="hibernate.max_fetch_depth" value="3"/>
<property name="hibernate.hbm2ddl.auto" value="update"/>
- <property name="hibernate.show_sql" value="true"/>
- <property name="hibernate.transaction.manager_lookup_class"
+ <property name="hibernate.show_sql" value="true"/>
+ <property name="hibernate.transaction.manager_lookup_class"
value="org.hibernate.transaction.BTMTransactionManagerLookup"/>
- </properties>
+ </properties>
</persistence-unit>
</persistence></programlisting>
- <para>This config file refers to a data source called "jdbc/processInstanceDS".
- The following Java fragment could be used to set up this data source, in this
- case we are using the file-based H2 database.</para>
+ <para>This configuration file refers to a data source called "jdbc/processInstanceDS".
+ The following Java fragment could be used to set up this data source, where
+ we are using the file-based H2 database.</para>
<programlisting>
PoolingDataSource ds = new PoolingDataSource();
@@ -217,15 +231,17 @@
<section>
<title>Transactions</title>
- Whenever you do not provide transaction boundaries inside your application, the engine
- will automatically execute each method invocation on the engine in a separate transaction.
- If this is acceptable behaviour, you don't need to do anything else. You can however
- also specify the transaction boundaries yourself. This allows you for example to combine
- multiple commands into one transaction. You need to register a transaction manager at
- the environment before using user-defined transactions. For example, the following sample
- uses the Bitronix transaction manager. Next, we use the Java Transaction API (JTA)
- to specify transaction boundaries, as shown below:
+ <para>Whenever you do not provide transaction boundaries inside your application,
+ the engine will automatically execute each method invocation on the engine
+ in a separate transaction. If this behavior is acceptable, you don't need to do
+ anything else. You can, however, also specify the transaction boundaries yourself.
+ This allows you, for example, to combine multiple commands into one transaction.</para>
+ <para>You need to register a transaction manager at the environment before
+ using user-defined transactions. The following sample code uses the Bitronix
+ transaction manager. Next, we use the Java Transaction API (JTA)
+ to specify transaction boundaries, as shown below:</para>
+
<programlisting>
// create the entity manager factory and register it in the environment
EntityManagerFactory emf =
@@ -240,7 +256,8 @@
JPAKnowledgeService.newStatefulKnowledgeSession( kbase, null, env );
// start the transaction
-UserTransaction ut = (UserTransaction) new InitialContext().lookup( "java:comp/UserTransaction" );
+UserTransaction ut =
+ (UserTransaction) new InitialContext().lookup( "java:comp/UserTransaction" );
ut.begin();
// perform multiple commands inside one transaction
@@ -248,108 +265,128 @@
ksession.startProcess( "MyProcess" );
ksession.fireAllRules();
-// now commit the transaction
+// commit the transaction
ut.commit();</programlisting>
</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>
+ <section>
+ <title>Process Definitions</title>
- <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 knowledge 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>
+ <para>Process definition files are usually written 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. It allows easy retrieval of
+ this knowledge using WebDAV or by employing a Knowledge 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>
+ <section>
+ <title>History Log</title>
- <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>
+ <para>In many cases it is useful (if not necessary) to store information
+ about the execution of 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 analyze the efficiency
+ of a particular process. 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>
- <section>
- <title>Persisting process events in a database</title>
+ <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 made persistent, for example in a database. Filters can be
+ used to only store the information you find relevant.</para>
- <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):
+ <section>
+ <title>Storing 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 the 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><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.
+ For this, it stores the process instance id and the process id of
+ the process instance it is being executed in, and the node
+ instance id and the 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>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" width="100%"
+ 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 ksession = ...
+StatefulKnowledgeSession ksession = ...;
WorkingMemoryDbLogger logger = new WorkingMemoryDbLogger(ksession);
// invoke methods one your session here
logger.dispose();</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 We refer to the JPA and Hibernate
- documentation for more information on how to do this.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. You should dispose the logger when it is no longer needed.</para>
+ <para>Note that this logger is like any other audit logger, which means
+ that you can add one or more filters by calling the method
+ <code>addFilter</code>d to ensure that only relevant information is
+ stored in the database. Only information accepted by all your filters will
+ appear in the database. You should dispose the logger when it is no
+ longer needed.</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>To specify the database where the information should be stored,
+ modify the file <filename>hibernate.cfg.xml</filename> file. By default,
+ it uses a memory-resident database (H2). Consult 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>
+ <para>All this information can easily be queried and 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. Class <code>ProcessInstanceDbLog</code> (in
+ package <code>org.drools.process.audit</code>) 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>
- <para>By default, the audit logger uses the H2 in-memory database that is recreated on startup. You can
- however change this default by including your own hibernate.cfg.xml configuration file. This allows you
- for example to change the underlying database, etc. We refer to the Hibernate documentation for more
- information on how to do this.</para>
+ <para>By default, the audit logger uses the H2 memory-resident database
+ that is recreated on startup. You can change this default by including
+ your own configuration file <filename>hibernate.cfg.xml</filename>. This
+ allows you, for example, to change the underlying database, etc.
+ Refer to the Hibernate documentation for more information on how to do
+ this.</para>
</section>
</section>
-
-</chapter>
+
+</chapter>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml 2009-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-ProcessModel/Chapter-ProcessModel.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -1,28 +1,28 @@
-<?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"
+<?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>Drools Flow process model</title>
+ <title>Drools Flow Process Model</title>
+
<para></para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="PNG" role=""
- fileref="images/Chapter-ProcessModel/ProcessModel.png"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="PNG" role=""
+ fileref="images/Chapter-ProcessModel/ProcessModel.png"/>
+ </imageobject>
</mediaobject>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="PNG" role=""
- fileref="images/Chapter-ProcessModel/ProcessInstanceModel.png"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="PNG" role=""
+ fileref="images/Chapter-ProcessModel/ProcessInstanceModel.png"/>
+ </imageobject>
</mediaobject>
-</chapter>
+</chapter>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-RulesAndProcesses/Chapter-RulesAndProcesses.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-RulesAndProcesses/Chapter-RulesAndProcesses.xml 2009-05-02 16:48:32 UTC (rev 26342)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-RulesAndProcesses/Chapter-RulesAndProcesses.xml 2009-05-02 18:56:36 UTC (rev 26343)
@@ -6,103 +6,121 @@
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>Rules and Processes</title>
+
<para>Drools Flow is a workflow and process engine that allows
- advanced integration of processes and rules. This chapter gives an
- overview of how to integrate rules and processes, ranging from simple
- to advanced.</para>
+ advanced integration of processes and rules. This chapter discusses
+ the integration of rules and processes, ranging from simple to
+ advanced scenarios.</para>
<section>
- <title>Why use rules in processes?</title>
- <para>
- Workflow languages that depend purely on process constructs (like nodes and connections) to describe
- the business logic of (a part of) an application tend to be quite complex. While these workflow
- constructs are very well suited to describe the overall control flow of an application, it can be
- very difficult to describe complex logic and exceptional situations. Therefore, executable processes
- tend to become very complex. We believe that, by extending a process engine with support for declarative
- rules in combination with these regular process constructs, this complexity can be kept under control.
- <orderedlist>
- <listitem>
- <para>Simplicity: Complex decisions are usually easier to specify using a set of rules. Rules can
- describe complex business logic more easily by using an advanced constraint language. Multiple
- rules can be combined, each describing a part of the business logic.</para>
- </listitem>
- <listitem>
- <para>Agility: Rules and processes can have a separate life cycle. This means that for example
- we can change the rules describing some crucial decision points without having to change the process
- itself. Rules can be added, removed or modified to fine-tune the behaviour of the process to the
- constantly evolving requirements and environment.</para>
- </listitem>
- <listitem>
- <para>Different scope: Rules can be reused accross processes or outside processes. Therefore, your
- business logic is not locked inside your processes.</para>
- </listitem>
- <listitem>
- <para>Declarative: Focus on describing 'what' instead of 'how'.</para>
- </listitem>
- <listitem>
- <para>Granularity: It is easy to write simple rules that handle specific circumstances. Processes
- more suited to describe the overall control flow but tend to become very complex if they also need
- to describe a lot of exceptional situations.</para>
- </listitem>
- <listitem>
- <para>Data-centric: Rules can easily handle large data sets.</para>
- </listitem>
- <listitem>
- <para>Performance: Rule evaluation is optimized.</para>
- </listitem>
- <listitem>
- <para>Advanced condition and action language: Rule languages supports advanced features like custom
- functions, collections, not, exists, for all, etc.</para>
- </listitem>
- <listitem>
- <para>Higher-level: Using DSLs, business editors, decision tables, decision trees, etc. your business
- logic could be described in a way that can be understood (and possibly even modified) by business users.</para>
- </listitem>
- </orderedlist>
- </para>
+ <title>Why Use Rules in Processes?</title>
+
+ <para>Workflow languages that depend purely on process constructs
+ (like nodes and connections) to describe the business logic of
+ applications tend to be quite complex. While these workflow
+ constructs are very well suited to describe the overall control
+ flow of an application, it can be very difficult to describe complex
+ logic and exceptional situations. Therefore, executable processes
+ tend to become very complex. We believe that, by extending a process
+ engine with support for declarative rules in combination with these
+ regular process constructs, this complexity can be kept under control.</para>
+ <orderedlist>
+ <listitem>
+ <para>Simplicity: Complex decisions are usually easier to specify
+ using a set of rules. Rules can pinpoint complex business logic
+ more easily, using their advanced constraint language. Multiple
+ rules can be combined, each describing a part of the business logic.</para>
+ </listitem>
+
+ <listitem>
+ <para>Agility: Rules and processes can have a separate life cycle.
+ This means that we can change the rules describing some crucial
+ decision points without having to change the process itself.
+ Rules can be added, removed or modified to fine-tune the behavior
+ of the process to the constantly evolving requirements and
+ environment.</para>
+ </listitem>
+ <listitem>
+ <para>Different scope: Rules can be reused across processes or
+ outside processes. Therefore, your business logic is not locked
+ inside your processes.</para>
+ </listitem>
+ <listitem>
+ <para>Declarativeness: Focus on describing "what" instead of "how".</para>
+ </listitem>
+ <listitem>
+ <para>Granularity: It is easy to write simple rules that handle
+ specific circumstances. Processes are more suited to describe
+ the overall control flow but tend to become very complex if they
+ also need to describe a lot of exceptional situations.</para>
+ </listitem>
+ <listitem>
+ <para>Data-centric: Rules can easily handle large data sets.</para>
+ </listitem>
+ <listitem>
+ <para>Performance: Rule evaluation is optimized.</para>
+ </listitem>
+ <listitem>
+ <para>Advanced condition and action language: Rule languages support
+ advanced features like custom functions, collections, conditional
+ elements, including quantifiers, etc.</para>
+ </listitem>
+ <listitem>
+ <para>High-level: By using DSLs, business editors, decision tables,
+ and decision trees, your business logic could be described in a way
+ that can be understood (and possibly even modified) by business users.</para>
+ </listitem>
+ </orderedlist>
</section>
<section>
- <title>Why integrate rules and processes in a single engine?</title>
- <para>
- Drools Flow combines a process and a rules engine in one software product. This offers several advantages
- (compared to trying to loosely coupling an existing process and rules product):
- <orderedlist>
- <listitem>
- <para>Simplicity: Easier for end user to combine both rules and processes.</para>
- </listitem>
- <listitem>
- <para>Encapsulation: Sometimes close integration between processes and rules is beneficial.</para>
- </listitem>
- <listitem>
- <para>Performance: No unnecessary passing, transformation or synchronization of data</para>
- </listitem>
- <listitem>
- <para>Learning curve: Easier to learn one product.</para>
- </listitem>
- <listitem>
- <para>Manageability: Easier to manage one product, rules and processes can be similar artefacts in a larger knowledge repository.</para>
- </listitem>
- <listitem>
- <para>Integration of features: We provide an integrated IDE, audit log, web-based management platform, repository, debugging, etc.</para>
- </listitem>
- </orderedlist>
- </para>
+ <title>Why Integrate Rules and Processes in a Single Engine?</title>
+
+ <para>Drools Flow combines a process and a rules engine in one software
+ product. This offers several advantages, compared to trying to loosely couple
+ an existing process and rules product.</para>
+ <orderedlist>
+ <listitem>
+ <para>Simplicity: Easier for end user to combine both rules and
+ processes.</para>
+ </listitem>
+ <listitem>
+ <para>Encapsulation: Sometimes close integration between processes
+ and rules is beneficial.</para>
+ </listitem>
+ <listitem>
+ <para>Performance: No unnecessary passing, transformation or synchronization
+ of data</para>
+ </listitem>
+ <listitem>
+ <para>Learning curve: Easier to learn one product.</para>
+ </listitem>
+ <listitem>
+ <para>Manageability: Easier to manage one product, rules and processes
+ can be similar artefacts in a larger knowledge repository.</para>
+ </listitem>
+ <listitem>
+ <para>Integration of features: We provide an integrated IDE, audit log,
+ web-based management platform, repository, debugging, etc.</para>
+ </listitem>
+ </orderedlist>
</section>
<section>
<title>Approach</title>
- <para>
- Workflow languages describe the order in which activities should be performed using a flow chart.
- A process engine is responsible for selecting which activities should be executed based on the current
- state of the executing processes.
- Rules on the other hand are composed of a set of conditions that describe when a rule is applicable
- and an action that is executed when the rule is applicable. The rules engine is then responsible for
- evaluating and executing the rules. It decides which rules need to be executed based on the current
- state of the application.
- </para>
+ <para> Workflow languages describe the order in which activities should
+ be performed using a flow chart. A process engine is responsible for
+ selecting which activities should be executed based on the current
+ state of the executing processes. On the other hand, rules are composed
+ of a set of conditions that describe when a rule is applicable
+ and an action that is executed when the conditions are met. The rules
+ engine is then responsible for evaluating and executing the rules. It
+ decides which rules need to be executed based on the current state of
+ the application.</para>
+
<mediaobject>
<imageobject>
<imagedata align="center" format="BMP" role=""
@@ -111,72 +129,77 @@
</mediaobject>
<para>
- Workflow processes are very good at describing the overall control flow of (possibly long-running)
- applications. However, processes that are used to define complex business decisions or contain a lot
- of exceptional situations or need to respond to various external events tend to become very complex.
- Rules on the other hand are very good at describing complex decisions and reasoning about large amounts
- of data or events. It is however not trivial to define long-running processes using rules.
- </para>
+ Workflow processes are very good at describing the overall control
+ flow of (possibly long-running) applications. However, processes that
+ are used to define complex business decisions, to handle a lot of
+ exceptional situations, and need to respond to various external events
+ tend to become very complex indeed. Rules are very good at describing
+ complex decisions and reasoning about large amounts of data or events.
+ It is, however, not trivial to define long-running processes using rules.</para>
- <para>
- In the past, users were forced to choose between defining their business logic using either a process
- or rules engine. Problems that required complex reasoning about large amounts of data used a rules engine,
- while users that wanted to focus on describing the control flow of their processes were forced to use a
- process engine. However, businesses nowadays might want to combine both processes and rules in order to
- be able to define all their business logic in the format that best suits their needs.
- </para>
+ <para>In the past, users were forced to choose between defining their
+ business logic using either a process or a rules engine. Problems that
+ required complex reasoning about large amounts of data used a rules engine,
+ while users that wanted to focus on describing the control flow of their
+ processes were forced to use a process engine. However, businesses nowadays
+ might want to combine both processes and rules in order to be able to define
+ all their business logic in the format that best suits their needs.</para>
- <para>
- Basically, both a rules and a process engine will derive the next steps that need to be executed by
- looking at its knowledge base (a set of rules or processes respectively) and the current known state
- of the application (the data in the working memory or the state of the executing process instances
- respectively). If we want to integrate rules and processes, we need an engine that can decide the next
- steps taking into account the logic that is defined inside both the processes and the rules.
- </para>
+ <para>Basically, both a rules and a process engine will derive the next steps
+ that need to be executed by looking at its Knowledge Base (a set of rules or
+ processes, respectively) and the current known state of the application (the
+ data in the Working Memory or the state of the executing process instances,
+ respectively). If we want to integrate rules and processes, we need an
+ engine that can decide the next steps taking into account the logic that is
+ defined inside both the processes and the rules.</para>
<section>
- <title>Teaching a rules engine about processes</title>
- <para>
- It is very difficult (and probably very inefficient as well) to extend a process engine to also take
- rules into account: the process engine would need to check for rules that might need to be executed
- at every step and would have to keep the data that is used by the rules engine up to date. However,
- it is not that difficult to 'teach' a rules engine about processes. If the current state of the processes
- is also inserted as part of the data the rules engine reasons about, and we 'learn' the rules engine how
- to derive the next steps of an executing process, the rules engine will then be able to derive the next steps
- taking both rules and processes into account.
- </para>
+ <title>Teaching a Rules Engine About Processes</title>
+
+ <para>It is very difficult (and probably very inefficient as well) to extend
+ a process engine to also take rules into account. The process engine would
+ need to check for rules that might need to be executed at every step and
+ would have to keep the data that is used by the rules engine up to date.
+ However, it is not that difficult to "teach" a rules engine about processes.
+ If the current state of the processes is also inserted as part of the
+ Working Memory data the rules engine reasons about, and we instruct the
+ rules engine how to derive the next steps of an executing process, the
+ rules engine will then be able to derive the next steps taking rules
+ and processes into account jointly.</para>
</section>
<section>
- <title>Inversion of control</title>
- <para>
- From the process perspective, this means that there is an inversion of control. In a normal
- proces engine, the engine is in full control and derives the next steps based on the current state of the
- process instance. If needed, it can contact external services to retrieve additional information (e.g. invoke
- a rules engine to request a decision), but it solely decides which steps to take, and is responsible for executing
- these steps.
- </para>
+ <title>Inversion of Control</title>
- <para>
- However, only our extended rules engine (that can reason about both rules and processes) is capable of deriving the next
- steps taking both rules and processes into account. If a part of the process needs to be executed, the rules engine
- will request the process engine to execute this step. Once this step has been performed, the process engine returns
- control to the rules engine to again derive the next steps. This means that the control on what to do next has been
- inverted: the process engine itself no longer decides the next step to take but our extended rules engine will be in
- control, notifying the process engine when to execute the next step.
- </para>
+ <para>From the process perspective, this means that there is an inversion
+ of control. A normal process engine exercises full control, deriving
+ the next steps based on the current state of the process instance. If
+ needed, it can contact external services to retrieve additional
+ information, but it solely decides which steps to take, and is alone
+ responsible for executing these steps.</para>
+
+ <para>However, only our extended rules engine (that can reason jointly
+ about rules and processes) is capable of deriving the next steps
+ taking both rules and processes into account. If a part of the process
+ needs to be executed, the rules engine will request the process engine
+ to execute this step. Once this step has been performed, the process
+ engine returns control to the rules engine to again derive the next
+ steps. This means that the control on what to do next has been inverted:
+ the process engine itself no longer decides the next step to take but
+ our enhanced rules engine will be in control, notifying the process
+ engine what to execute next, and when.</para>
</section>
</section>
-
<section>
<title>Example</title>
- <para>
- The drools-examples project contains a sample process (org.drools.examples.process.order)
- that illustrates some of the advantages of being able to combine processes and rules. This
- process describes an order application where incoming orders are validated, possible discount
- are calculated and shipping of the goods is requested.
+
+ <para>The drools-examples project contains a sample process
+ (<filename>org.drools.examples.process.order</filename>) that illustrates
+ some of the advantages of being able to combine processes and rules. This
+ process describes an order application where incoming orders are validated,
+ discounts are calculated and shipping of the goods is requested.
</para>
<mediaobject>
@@ -187,38 +210,59 @@
</mediaobject>
<section>
- <title>Evaluating a set of rules in your process</title>
+ <title>Evaluating a Set of Rules in Your Process</title>
+
<para>Drools Flow can easily include a set of rules as part of the process.
The rules that need to be evaluated should be grouped in a ruleflow
- group (using the ruleflow-group rule attribute) and a RuleSet node
- can be used to trigger the evaluation of these rules in your process. This example
- uses two RuleSet nodes in the process: one for the validation of the order
- and one for calculating the discount. For example, one of the rules for validiting
- an order looks like this (note the ruleflow-group attribute, which makes sure that
- this rule is evaluated as part of the RuleSet node with the same ruleflow-group):</para>
+ group, using the <kw>ruleflow-group</kw> rule attribute. Activating a
+ RuleSet node for the group triggers the evaluation of these rules in your
+ process. This example uses two RuleSet nodes in the process: one for the
+ validation of the order and one for calculating the discount. For example,
+ one of the rules for validiting an order is shown below. Note the
+ <kw>ruleflow-group</kw> attribute, which ensures that this rule is evaluated
+ as part of the RuleSet node with the same ruleflow group shown in the
+ figure.</para>
+ <programlisting>
+rule "Invalid item id"
+ ruleflow-group "validate"
+ lock-on-active true
+when
+ o: Order()
+ i: Order.OrderItem() from o.getOrderItems()
+ not (Item() from itemCatalog.getItem(i.getItemId()))
+then
+ System.err.println("Invalid item id found!");
+ o.addError("Invalid item id " + i.getItemId());
+end</programlisting>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-RulesAndProcesses/validation.bmp"/>
- </imageobject>
- </mediaobject>
+ <figure>
+ <title>RuleSet node and one of its rules</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" format="BMP" role=""
+ fileref="images/Chapter-RulesAndProcesses/validation.bmp"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
</section>
<section>
- <title>Using rules for evaluating constraints</title>
- <para>Rules can be used for expressing and evaluating complex constraints
- in your process. For example, when a decision should be made which execution
- paths should be selected at a split, rules could be used to define these
- conditions. Similarly, a wait state could use a rule to define how long
- to wait. This example uses rules for deciding the next action after validating
- the order. If the order contains errors, a sales representative should try to
- correct the order. Orders with a value > 1000$ are more important and a senior
- sales representative should follow up the order. All other orders should just
- proceed normally. An decision node is used to select one of these alternatives,
- and rules are used to describe the constraints for each of them:</para>
+ <title>Using Rules for Evaluating Constraints</title>
+ <para>Rules can be used for expressing and evaluating complex
+ constraints in your process. For example, when to decide
+ about the choice of the execution path at a Split node, rules
+ could be used to define these conditions. Similarly, a Wait
+ state could use a rule to define the wait duration. This example
+ uses rules for deciding the next action after validating
+ the order. If the order contains errors, a sales representative
+ should try to correct the order. Orders with a value > 1000$
+ are more important, so that a senior sales representative should
+ attend to the order. All other orders should just proceed normally.
+ A decision node is used to select one of these alternatives,
+ and rules are used to describe the constraints for each of them.</para>
+
<mediaobject>
<imageobject>
<imagedata align="center" format="BMP" role=""
@@ -229,89 +273,138 @@
</section>
<section>
- <title>Assignment rules</title>
- <para>Human tasks can be used in a process to describe work that needs to
- be executed by a human actor. Which actor could be based on the current
- state of the process, and the history. Assignment rules can be used to
- describe how to the actor based on this information. These assignment rules
- will then be applied automatically whenever a new human task needs to be
- executed.</para>
+ <title>Assignment Rules</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-RulesAndProcesses/assignment.bmp"/>
- </imageobject>
- </mediaobject>
+ <para>Human tasks can be used in a process to describe work that
+ needs to be executed by a human actor. The selection of the actor
+ could be based on the current state of the process and the history.
+ Assignment rules describe how to determine the actor, based on this
+ information. These assignment rules will then be applied
+ automatically whenever a new human task needs to be executed.</para>
+ <para>Note that the rules shown below are written in a
+ Domain Specific Language (DSL), tailored to the specific requirements
+ for formulating conditions in the order processing environment.</para>
+
+ <programlisting>
+/********** Generic assignment rules **********/
+
+rule "Assign 'Correct Order' to any sales representative"
+ salience 30
+ when
+ There is a human task
+ - with task name "Correct Order"
+ - without actor id
+ then
+ Set actor id "Sales Representative"
+end
+
+/********** Assignment rules for the RuleSetExample process **********/
+
+rule "Assign 'Follow-up Order' to a senior sales representative"
+ salience 40
+ when
+ Process "org.drools.examples.process.ruleset.RuleSetExample" contains a human task
+ - with task name "Follow-up Order"
+ - without actor id
+ then
+ Set actor id "Senior Sales Representative"
+end</programlisting>
</section>
<section>
- <title>Describing exceptional situations using rules</title>
- <para>Rules can be used for describing exceptional situations and how to respond
- to these situations. Adding all this information in the control flow of the main
- process would make the basic process much more complex. Rules can be used to
- handle each of these situations separately, without making the core process more
- complex. It also makes it much easier to adapt existing processes to take new
- unanticipated events into account.</para>
+ <title>Describing Exceptional Situations Using Rules</title>
+
+ <para>Rules can be used for describing exceptional situations
+ and how to respond to these situations. Adding all this information
+ in the control flow of the regular process makes the basic process
+ much more complex. Rules can be used to handle each of these
+ situations separately, leaving the core process in its simple form.
+ It also makes it much easier to adapt existing processes to take
+ previously unanticipated events into account.</para>
</section>
<section>
- <title>Modularizing concerns using rules</title>
- <para>The process defines the overall control flow. Rules could be used
- to add additional concerns to this process without making the overall control
- flow more complex. For example, rules could be defined to log certain information
- during the execution of the process. The original process is not altered and
- all logging functionality is cleanly modularized as a set of rules. This
- greatly improves reusability (allows users to easily apply the same strategy
- on different processes), readability (control flow of the original process
- is still the same) and modifiability (you can easily add, remove or change the
- logging strategy by adding, removing or changing the rules, the process should not
- be modified).</para>
+ <title>Modularizing Concerns Using Rules</title>
+
+ <para>The process defines the overall control flow. Rules could
+ be used to add additional concerns to this process without making
+ the overall control flow more complex. For example, rules could
+ be defined to log certain information during the execution of the
+ process. The original process is not altered, whereas all logging
+ functionality is cleanly modularized as a set of rules. This
+ greatly improves reusability, allowing users to easily apply the
+ same strategy to different processes, readability (by not altering
+ the control flow of the original process) and maintainability, due
+ to the separation of the logging strategy rules from those of the
+ process itself.</para>
</section>
<section>
- <title>Using rules to dynamically alter the behaviour of the process</title>
- <para>Rules can be used to dynamically fine-tune the behaviour of your processes.
- For example, if a problem is encountered at runtime with one of the processes, new rules
- could be added at runtime to log additional information or handle
- specific cases of the process. Once the problem is solved or the circumstances have
- changed, these rules can easily be removed again. Based on
- the current status, different strategies could be selected dynamically.
- For example, based on the current load of all the services, rules could be used
- to optimize the process to the current load. This process contains a simple example
- that allows you to dynamically add or remove logging for the 'Check Order' task. When the
- 'Debugging output' checkbox in the main application window is checked, a rule is dynamically
- loaded to add a logging statement to the console whenever the 'Check Order' task is requested.
- Unchecking the box will dynamically remove the rule again.
- </para>
+ <title>Rules for Altering Process Behavior Dynamically</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-RulesAndProcesses/dynamicLogging.bmp"/>
- </imageobject>
- </mediaobject>
+ <para>Rules let you dynamically fine-tune the behavior of your processes.
+ Imagine that a problem is encountered, at runtime, with one of the
+ processes. Now, new rules could be added, at runtime, to log additional
+ information or for handling specific process states. Once the problem
+ is solved or the circumstances have changed, these rules can easily be
+ removed again. Based on the current status, different strategies
+ could be selected dynamically. For example, based on the current load
+ of all the services, rules could be used to optimize the process to
+ the current load. This process contains a simple example that allows
+ you to dynamically add or remove logging for the "Check Order" task.
+ When the "Debugging output" checkbox in the main application window is
+ checked, the rule shown below is loaded dynamically, to write log
+ output to the console whenever the "Check Order" task is requested.
+ Unchecking the box will dynamically remove the rule again.</para>
+ <programlisting>
+rule "Log the execution of 'Correct Order'"
+ salience 25
+when
+ workItemNodeInstance: WorkItemNodeInstance( workItemId <= 0, node.name == "Correct Order" )
+ workItem: WorkItemImpl( state == WorkItemImpl.PENDING ) from workItemNodeInstance.getWorkItem()
+then
+ ProcessInstance proc = workItemNodeInstance.getProcessInstance();
+ VariableScopeInstance variableScopeInstance =
+ (VariableScopeInstance)proc.getContextInstance( VariableScope.VARIABLE_SCOPE );
+ System.out.println( "LOGGING: Requesting the correction of " +
+ variableScopeInstance.getVariable("order"));
+end</programlisting>
+
</section>
<section>
- <title>Integrated tooling</title>
- <para>Processes and rules are integrated in the Drools Eclipse IDE. Both processes and rules
- are simply considered as different types of business logic, but are managed almost identical.
- For example, loading a process or a set of rules into the engine is very similar:</para>
+ <title>Integrated Tooling</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-RulesAndProcesses/loading.bmp"/>
- </imageobject>
- </mediaobject>
+ <para>Processes and rules are integrated in the Drools Eclipse IDE. Both
+ processes and rules are simply considered as different types of business
+ logic, to be managed almost identically. For example, loading a process
+ or a set of rules into the engine is very similar. Also, different
+ rule implementations, such DRL or DSL, are handled in a uniform way.</para>
- <para>Our audit log also contains an integrated view, showing how rules and processes are influencing
- each other. For example, a part of the log shows how the '5% discount' rule is executed as part of the
- 'Calculate Discount' node.</para>
+ <programlisting>
+private static KnowledgeBase createKnowledgeBase() throws Exception {
+ KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
+ kbuilder.add( ResourceFactory.newClassPathResource(
+ "RuleSetExample.rf", OrderExample.class), ResourceType.DRF );
+ kbuilder.add( ResourceFactory.newClassPathResource(
+ "workflow_rules.drl", OrderExample.class), ResourceType.DRL );
+ kbuilder.add( ResourceFactory.newClassPathResource(
+ "assignment.dsl", OrderExample.class), ResourceType.DSL );
+ kbuilder.add( ResourceFactory.newClassPathResource(
+ "assignment.dslr", OrderExample.class), ResourceType.DSLR );
+ KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() );
+ return kbase;
+}</programlisting>
+
+ <para>Our audit log also contains an integrated view, showing how rules
+ and processes are influencing each other. For example, a part of the
+ log shows how rule "5% discount" is executed as part of the node
+ "Calculate Discount".</para>
+
<mediaobject>
<imageobject>
<imagedata align="center" format="BMP" role=""
@@ -322,20 +415,41 @@
</section>
<section>
- <title>Domain-specific rules and processes</title>
- <para>Rules do not need to be defined using the core rule language syntax, but they also can be defined
- using our more advanced rule editors like domain-specific languages, decision tables, guided editors, etc.
- Our examples defines a domain-specific language for describing assignment rules, based on the type of
- task, its properties, the process it is defined in, etc. This makes the assignment rules much more
- understandable for non-experts.</para>
+ <title>Domain-specific Rules and Processes</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" format="BMP" role=""
- fileref="images/Chapter-RulesAndProcesses/assignment.bmp"/>
- </imageobject>
- </mediaobject>
+ <para>Rules do not need to be defined using the core rule language
+ syntax, but they also can be defined using our more advanced rule
+ editors, using domain-specific languages, decision tables, guided
+ editors, etc. Our example defines a domain-specific language for
+ describing assignment rules, based on the type of task, its properties,
+ the process it is defined in, etc. This makes the assignment rules
+ much more understandable for non-experts.</para>
+ <programlisting>
+/********** Generic assignment rules **********/
+
+rule "Assign 'Correct Order' to any sales representative"
+ salience 30
+ when
+ There is a human task
+ - with task name "Correct Order"
+ - without actor id
+ then
+ Set actor id "Sales Representative"
+end
+
+/********** Assignment rules for the RuleSetExample process **********/
+
+rule "Assign 'Follow-up Order' to a senior sales representative"
+ salience 40
+ when
+ Process "org.drools.examples.process.ruleset.RuleSetExample" contains a human task
+ - with task name "Follow-up Order"
+ - without actor id
+ then
+ Set actor id "Senior Sales Representative"
+end</programlisting>
+
</section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-RulesAndProcesses/validation.bmp
===================================================================
(Binary files differ)
More information about the jboss-svn-commits
mailing list