Author: jbarrez Date: 2009-12-21 10:20:53 -0500 (Mon, 21 Dec 2009) New Revision: 6006 Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.01.png jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.02.png jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.03.png jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.04.png jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.png Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml Log: JBPM-2675 and JBPM-2660: added complete example to BPMN 2.0 documentation Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.01.png =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.01.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.02.png =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.02.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.03.png =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.03.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.04.png =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.console.04.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.png =================================================================== (Binary files differ) Property changes on: jbpm4/trunk/modules/devguide/src/main/docbook/en/images/bpmn2.vacationrequest.example.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml =================================================================== --- jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml 2009-12-21 10:03:33 UTC (rev 6005) +++ jbpm4/trunk/modules/devguide/src/main/docbook/en/modules/ch03-Bpmn2.xml 2009-12-21 15:20:53 UTC (rev 6006) @@ -136,16 +136,6 @@ </section> - <section id="gettingStartedWithBpmn2" > - - <title>Getting started</title> - - <para> - - </para> - - </section> - <section id="Bpmn2Execution" > <title>Bpmn 2.0 execution</title> @@ -870,4 +860,205 @@ </section> <!-- End of basic constructs section --> + <section id="completeExample"> + + <title>Complete example (including console task forms)</title> + + <para> + <emphasis role="bold">Prerequisites</emphasis>: to run the example, we assume that a working + jBPM console has been installed on your JBoss server. If not, please run the 'demo.setup.jboss' + install script first. + </para> + + <para> + The business process we're implementing looks as follows: + <mediaobject><imageobject><imagedata align="center" fileref="images/bpmn2.vacationrequest.example.png"/></imageobject></mediaobject> + You might recognize this example, since we’ve also implemented it in + JPDL as an example in our distribution. + </para> + <para> + The business process is simple: an employee can start a new process and + make a request for a certain amount of vacation days. After the request + task has been completed, the manager will find a verification task in + its tasklist. The Manager can now decide to accept or reject this + request. Depending on the outcome (that’s the little rhombus on the + outgoing sequence flow - it means there is a conditional expression on the sequence flow), + a rejection message is send or the process ends. Do note that in fact we've used a shortcut + here: instead of putting expressions on the outgoing sequence flow of the 'verify request' + task, we've could have used an exclusive gateway after the user task to control the flow + through the process. Also note that since we haven't implemented swimlanes yet (probably + the next release), it's difficult to actually see who does what in the business process. + </para> + + <para> + The XML version of this process looks as follows: + <programlisting> +&lt;process id=&quot;vacationRequestProcess&quot; name=&quot;BPMN2 Example process using task forms&quot;&gt; + + &lt;startEvent id=&quot;start&quot; /&gt; + + &lt;sequenceFlow id=&quot;flow1&quot; name=&quot;fromStartToRequestVacation&quot; + sourceRef=&quot;start&quot; targetRef=&quot;requestVacation&quot; /&gt; + + &lt;userTask id=&quot;requestVacation&quot; name=&quot;Request Vacation&quot; + implementation=&quot;other&quot;&gt; + &lt;potentialOwner resourceRef=&quot;user&quot; /&gt; + &lt;rendering id=&quot;requestForm&quot;&gt; + &lt;jbpm:form&gt;org/jbpm/examples/bpmn/usertask/taskform/request_vacation.ftl&lt;/jbpm:form&gt; + &lt;/rendering&gt; + &lt;/userTask&gt; + + &lt;sequenceFlow id=&quot;flow2&quot; + name=&quot;fromRequestVacationToVerifyRequest&quot; sourceRef=&quot;requestVacation&quot; + targetRef=&quot;verifyRequest&quot; /&gt; + + &lt;userTask id=&quot;verifyRequest&quot; name=&quot;Verify Request&quot; + implementation=&quot;other&quot;&gt; + &lt;potentialOwner resourceRef=&quot;manager&quot; /&gt; + &lt;rendering id=&quot;verifyForm&quot;&gt; + &lt;jbpm:form&gt;org/jbpm/examples/bpmn/usertask/taskform/verify_request.ftl&lt;/jbpm:form&gt; + &lt;/rendering&gt; + &lt;/userTask&gt; + + &lt;sequenceFlow id=&quot;flow3&quot; name=&quot;fromVerifyRequestToEnd&quot; + sourceRef=&quot;verifyRequest&quot; targetRef=&quot;theEnd&quot;&gt; + &lt;conditionExpression xsi:type=&quot;tFormalExpression&quot;&gt; + ${verificationResult == 'OK'} + &lt;/conditionExpression&gt; + &lt;/sequenceFlow&gt; + + &lt;sequenceFlow id=&quot;flow4&quot; + name=&quot;fromVerifyRequestToSendRejectionMessage&quot; sourceRef=&quot;verifyRequest&quot; + targetRef=&quot;sendRejectionMessage&quot;&gt; + &lt;conditionExpression xsi:type=&quot;tFormalExpression&quot;&gt; + ${verificationResult == 'Not OK'} + &lt;/conditionExpression&gt; + &lt;/sequenceFlow&gt; + + &lt;scriptTask id=&quot;sendRejectionMessage&quot; name=&quot;Send rejection Message&quot; + scriptLanguage=&quot;bsh&quot;&gt; + &lt;script&gt; + &lt;![CDATA[System.out.println(&quot;Vacation request refused!&quot;);]]&gt; + &lt;/script&gt; + &lt;/scriptTask&gt; + + &lt;sequenceFlow id=&quot;flow5&quot; + name=&quot;fromSendRejectionMessageToEnd&quot; sourceRef=&quot;sendRejectionMessage&quot; + targetRef=&quot;theEnd&quot; /&gt; + + &lt;endEvent id=&quot;theEnd&quot; name=&quot;End&quot; /&gt; +&lt;/process&gt; + </programlisting> + <emphasis role="bold">Note</emphasis>: this example is already installed when you've + used the demo setup. Also note that we're using a Script Task here, to quickly write + something as output instead of sending a real message (the diagram is showing a Service + Task). Also note that we've taken some shortcuts here regarding task assignment (will + be fixed in the next release). + </para> + + <para> + The constructs used in this implementation are all covered in the previous section. + Also note that we're using the <emphasis role="bold">taskform functionality</emphasis> + here, which is a custom jBPM extension for the <emphasis role="bold">rendering</emphasis> + element of a User task. + <programlisting> +&lt;userTask id=&quot;verifyRequest&quot; name=&quot;Verify Request&quot; + implementation=&quot;other&quot;&gt; + &lt;potentialOwner resourceRef=&quot;manager&quot; /&gt; + &lt;rendering id=&quot;verifyForm&quot;&gt; + &lt;jbpm:form&gt;org/jbpm/examples/bpmn/usertask/taskform/verify_request.ftl&lt;/jbpm:form&gt; + &lt;/rendering&gt; +&lt;/userTask&gt; + </programlisting> + The mechanism regarding task forms for BPMN 2.0 is complete equivalent to that of JPDL. + The form itself is a <ulink url="http://freemarker.org/">Freemarker</ulink> template file + that needs to be incorporated in the deployment. For example, the 'verify_request' form + looks like as follows. + <programlisting> +&lt;html&gt; + &lt;body&gt; + + &lt;form action=&quot;${form.action}&quot; method=&quot;POST&quot; enctype=&quot;multipart/form-data&quot;&gt; + + &lt;h3&gt;Your employee, ${employee_name} would like to go on vacation&lt;/h3&gt; + Number of days: ${number_of_days}&lt;br/&gt; + + &lt;hr&gt; + + In case you reject, please provide a reason:&lt;br/&gt; + &lt;input type=&quot;textarea&quot; name=&quot;reason&quot;/&gt;&lt;br/&gt; + + &lt;input type=&quot;submit&quot; name=&quot;verificationResult&quot; value=&quot;OK&quot;&gt; + &lt;input type=&quot;submit&quot; name=&quot;verificationResult&quot; value=&quot;Not OK&quot;&gt; + + &lt;/form&gt; + &lt;/body&gt; +&lt;/html&gt; + </programlisting> + Note that <emphasis role="bold">process variables can be + used using the ${my_process_variable} construct.</emphasis> Also note that named + input controls (eg. input field, submit button) can be used to + <emphasis role="bold">define new process variables</emphasis>. + For example, the text input of the following field will be stored as the process + variable 'reason' + <programlisting> +&lt;input type=&quot;textarea&quot; name=&quot;reason&quot;/&gt; + </programlisting> + Note that there are two submit buttons (which makes sense if you look at the 'OK' and 'Not OK' + sequence flows going out the 'request vacation' task. By pressing one of these buttons, the + process variable 'verificationResult' will be stored. It can then be used to evaluate the + outgoing sequence flow: + <programlisting> +&lt;sequenceFlow id=&quot;flow3&quot; name=&quot;fromVerifyRequestToEnd&quot; + sourceRef=&quot;verifyRequest&quot; targetRef=&quot;theEnd&quot;&gt; + &lt;conditionExpression xsi:type=&quot;tFormalExpression&quot;&gt; + ${verificationResult == 'OK'} + &lt;/conditionExpression&gt; +&lt;/sequenceFlow&gt; + </programlisting> + </para> + + <para> + The process can now be deployed. You can use the ant deploy task for this (see examples), + or you can point your jBPM configuration to the database of the console. To deploy + your process programmatically, you need to add the task forms to your deployment: + <programlisting> +NewDeployment deployment = repositoryService.createDeployment(); +deployment.addResourceFromClasspath(&quot;org/jbpm/examples/bpmn/usertask/taskform/vacationrequest.bpmn.xml&quot;); +deployment.addResourceFromClasspath(&quot;org/jbpm/examples/bpmn/usertask/taskform/request_vacation.ftl&quot;); +deployment.addResourceFromClasspath(&quot;org/jbpm/examples/bpmn/usertask/taskform/verify_request.ftl&quot;); +deployment.deploy(); + </programlisting> + You can now embed (or run on a standalone server) this business process, by using the + familiar jBPM API operations. For example, process instances can now be started using the + key (ie. the process id for BPMN 2.0): + <programlisting> +ProcessInstance pi = executionService.startProcessInstanceByKey(&quot;vacationRequestProcess&quot;); + </programlisting> + Or tasks list can be retrieved: + <programlisting> +Task requestTasktask = taskService.createTaskQuery().candidate(&quot;peter&quot;).uniqueResult(); + </programlisting> + </para> + + <para> + When deploying to the jBPM console database, you should see our new business process popping up. + <mediaobject><imageobject><imagedata align="center" fileref="images/bpmn2.vacationrequest.example.console.01.png"/></imageobject></mediaobject> + + After you start a new process, a new task should be available in the employee's tasklist. + When clicking on 'view', the task form will be displayed, requesting to fill in some + variables for further use in the process. + <mediaobject><imageobject><imagedata align="center" fileref="images/bpmn2.vacationrequest.example.console.02.png"/></imageobject></mediaobject> + + After task completion, the manager will find a new verification task in his task list. + He can now accept or reject the vacation request, based on the input of the employee. + <mediaobject><imageobject><imagedata align="center" fileref="images/bpmn2.vacationrequest.example.console.03.png"/></imageobject></mediaobject> + + Since the database schema remains unchanged when we added BPMN 2.0 on top of the jBPM PVM, all + existing reports can be applied to our new BPMN 2.0 processes. + <mediaobject><imageobject><imagedata align="center" fileref="images/bpmn2.vacationrequest.example.console.04.png"/></imageobject></mediaobject> + </para> + + </section> + </chapter>