Author: ochikvina Date: 2010-05-31 06:16:48 -0400 (Mon, 31 May 2010) New Revision: 22439 Modified: trunk/jbpm/docs/reference/en-US/tasks.xml Log: https://jira.jboss.org/browse/TOOLSDOC-23- Reviewed restructured jbpm guide.Resolved some text issues and mistakes. Modified: trunk/jbpm/docs/reference/en-US/tasks.xml =================================================================== --- trunk/jbpm/docs/reference/en-US/tasks.xml 2010-05-31 07:00:21 UTC (rev 22438) +++ trunk/jbpm/docs/reference/en-US/tasks.xml 2010-05-31 10:16:48 UTC (rev 22439) @@ -1,671 +1,671 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter> - <?dbhtml filename="jboss_jbpm_runtime_installation.html"?> - <chapterinfo> - <keywordset> - <keyword>jBPM</keyword> - <keyword>designer</keyword> - <keyword>process</keyword> - <keyword>JBoss Developer Studio</keyword> - <keyword>jBPM runtime</keyword> - <keyword>JBoss</keyword> - <keyword>Process</keyword> - <keyword>Definition</keyword> - </keywordset> - - </chapterinfo> - <title>Tasks</title> -<section id="jboss_jbpm_runtime_installation" xreflabel="jboss_jbpm_runtime_installation"> - - <title>JBoss jBPM Runtime Installation</title> - <para>The main purpose of this chapter is to let you know how to launch the <property>JBoss - jBPM</property> (business process management).</para> - <para>The jBPM plugin (jBPM Designer) is already included in the <property>JBoss Tools</property>. - To make it work, you should only download the jBPM runtime (<ulink - url="http://sourceforge.net/project/showfiles.php?group_id=70542&... - >jbpm-jpdl-3.2.3</ulink> currently) and specify the directory where you extracted the runtime - either when you create a jBPM project or by using the jBPM preference pages.</para> - - <note> - <title>Note:</title> - <para>Try to avoid using spaces in the names of installation folders. It can provoke problems in - some situations with Sun-based VMs.</para> - </note> - - <para>Navigate to <emphasis> - <property>Window &gt; Preferences &gt; JBoss jBPM &gt; Runtime Locations</property>. - </emphasis> Here you can add, edit and remove JBoss jBPM installation locations. Click <emphasis> - <property>Add</property> - </emphasis> button. In the dialog that appeared enter a name for a newly added jBPM runtime and - point to the correct location of this package on your harddrive. Click <emphasis> - <property>OK</property> - </emphasis> then click <emphasis> - <property>OK</property> - </emphasis> again.</para> - - <figure> - <title>Adding jBPM Location</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/runtime_installation/runtime_installation_1.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Now, when you have a runtime installed, we are going to demonstrate some powerful features of - the jBPM.</para> -</section> - <section id="GuidedTourJBossjBPMGPD" xreflabel="GuidedTourJBossjBPMGPD"> - <?dbhtml filename="GuidedTourJBossjBPMGPD.html"?> - - <title>A Guided Tour of JBoss jBPM GPD</title> - <para>In this chapter we suggest a step-by-step walk-through of creating and configuring your - own simple process. Let's try to organize a new jBPM project.</para> - <para>A wizard for creating a jBPM project is included in the GPD plugin. We have opted to - create a project based on a template already containing a number of advanced artifacts that - we will ignore for this section. In the future we will elaborate this wizard and offer the - possibility to create an empty jBPM project as well as projects based on templates taken - from the jBPM tutorial.</para> - <section id="CreatingjBPMProject"> - <?dbhtml filename="CreatingjBPMProject.html"?> - <title>Creating a jBPM Project</title> - <para>This section will show you how to use the Creation wizard for creating a new jBPM - project with already included source folders.</para> - <para>At first you should select <emphasis> - <property>File &gt;New Project...</property> - </emphasis> and then <emphasis> - <property>JBoss jBPM &gt; Process Project</property> - </emphasis> in the New Project dialog:</para> - <figure> - <title>New Project Dialog</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_1.png"/> - </imageobject> - </mediaobject> - </figure> - <para> Clicking <emphasis> - <property>Next</property> - </emphasis> brings us to the wizard page where it&apos;s necessary to specify the - name and location for the project. We choose, for example, <emphasis> - <property>HellojBPM</property> - </emphasis> as the name and accept the default location. </para> - <figure> - <title>Process Name and Location</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_2.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Thus, our project will be created in the workspace root directory by default. If you - want to change the directory for your future project, deselect <emphasis> - <property>Use default location</property> - </emphasis> and click <emphasis> - <property>Browse...</property> - </emphasis> button to set needed location or simply type it.</para> - <para>On the next screen you&apos;ll be prompted to select the core jBPM location that - we have defined in the previous chapter.</para> - <figure> - <title>Core jBPM Location Specifying</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_9.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Clicking on <emphasis> - <property>Finish</property> - </emphasis> results in the project being generated. The wizard creates four source - folders: one for the processes (<emphasis> - <property>src/main/jpdl</property> - </emphasis>), one for the java sources (<emphasis> - <property>src/main/java</property> - </emphasis>), one for the unit tests (<emphasis> - <property>src/test/java</property> - </emphasis>) and one for the resources such as the jbpm.properties and the - hibernate.properties files (<emphasis> - <property>src/main/config</property> - </emphasis>). In addition a classpath container with all the core jBPM libraries is - added to the project</para> - <figure> - <title>Layout of the Process Project</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_3.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Looking inside the different source folders will reveal a number of other artifacts - that were generated, but we will leave these untouched for the moment. Instead, we will - look at another wizard that enables us to create an empty process definition.</para> - </section> - <section id="creating_an_empty_process_definition"> - <?dbhtml filename="creating_an_empty_process_definition.html"?> - <title>Creating an Empty Process Definition</title> - <para>Now when the project is set up, we can use a Creation wizard to create an empty - process definition. Bring up the <emphasis> - <property>New</property> - </emphasis> wizard by clicking the <emphasis> - <property>File &gt; New &gt; Other...</property> - </emphasis> menu item. The wizard opens on the <emphasis> - <property>Select Wizard</property> - </emphasis> page.</para> - <figure> - <title>The Select Wizard Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_4.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Selecting the <emphasis> - <property>JBoss jBPM</property> - </emphasis> category, then the <emphasis> - <property>Process Definition</property> - </emphasis> item and clicking on the <emphasis> - <property>Next</property> - </emphasis> button brings us to the <emphasis> - <property>Create Process Definition</property> - </emphasis> page.</para> - <figure> - <title>The Create New Process Defining Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_5.png"/> - </imageobject> - </mediaobject> - </figure> - <para>We choose <emphasis> - <property>hello</property> - </emphasis> as the name of the process archive file. Click on the <emphasis> - <property>Finish</property> - </emphasis> button to end the wizard and open the process definition editor.</para> - <figure> - <title>The Process Definition Editor</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_6.png" - scale="60"/> - </imageobject> - </mediaobject> - </figure> - - - <para>You can see in the Package Explorer that creating a process definition involves - creating a folder with the name of the process definition and populating this folder - with two .xml files : <emphasis> - <property>gpd.xml</property> - </emphasis> , <emphasis> - <property>processdefinition.xml</property> </emphasis> and a .jpg file:<emphasis> - <property>processimage.jpg</property></emphasis>.</para> - <para>The <emphasis> - <property>gpd.xml</property> - </emphasis> contains the graphical information used by the process definition editor. - The <emphasis> - <property>processdefinition.xml</property> - </emphasis> file contains the actual process definition info. - The graphical view of the process is automatically saved in <emphasis> - <property>processimage.jpg</property> - </emphasis>file. - At present, the GPD assumes that these three files are siblings. More - sophisticated configuration will be supported later.</para> - - <section id="minimal_process_definition"> - <?dbhtml filename="minimal_process_definition.html"?> - <title>A Minimal Process Definition</title> - <para>Now we are ready to create a very simple process definition consisting of a begin - state, an intermediate state and an end state.</para> - <para>To make the configuration of actions much easier it&apos;s better to use the - <emphasis>><property>"jBPM jPDL 3"</property></emphasis> perspective. It provides the tabbed Properties Editor which allows to configure - all the relevant properties of the current selected item. </para> - - <section id="adding_the_nodes"> - <?dbhtml filename="adding_the_nodes.html"?> - <title>Adding the Nodes</title> - <para>At first select respectively <emphasis> - <property>Start</property>, </emphasis> - <emphasis> - <property>State</property> - </emphasis> and <emphasis> - <property>End</property> - </emphasis> on the tools palette and click on the canvas to add these nodes to - the process definition. The result should look similar to this:</para> - <figure> - <title>A Simple Process With Three Nodes</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_7.png" - scale="60"/> - </imageobject> - </mediaobject> - </figure> - </section> - <section id="adding_transitions"> - <?dbhtml filename="adding_transitions.html"?> - <title>Adding Transitions</title> - <para>Then, we will connect the nodes with transitions. To do that select the <emphasis> - <property>Transition</property> - </emphasis> tool in the tools palette and click on the <emphasis> - <property>Start</property> - </emphasis> node, then move to the <emphasis> - <property>State</property> - </emphasis> node and click again to see the transition being drawn. Perform the - same steps to create a transition from the <emphasis> - <property>State</property> - </emphasis> node to the <emphasis> - <property>End</property> - </emphasis> node. The result will look like:</para> - <figure> - <title>A Simple Process With Transitions</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_8.png" - scale="60"/> - </imageobject> - </mediaobject> - </figure> - <para>Now, when you&apos;ve got background knowledge of simple project creation, - let&apos;s move to more advanced tools.</para> - </section> - </section> - </section> - </section> - <section id="The_JBoss_jBPM_Int_Mech" xreflabel="The_JBoss_jBPM_Int_Mech"> - <?dbhtml filename="The_JBoss_jBPM_Int_Mech.html"?> - - <title>Actions : The JBoss jBPM Integration Mechanism</title> - - <para> In this chapter we will show how to do software integration with <property>JBoss - jBPM</property>. The standard mechanism to implement this is to wrap the functionality you - want to integrate in a class that implements the <emphasis> - <property>ActionHandler</property> - </emphasis> interface. In order to demonstrate it let's specify Hello World action for our - process.</para> - - <section> - <title>Creating a Hello World Action</title> - - <para>Each Hello World process should integrate one or more Hello World actions, so this is - what we will be doing. We can integrate custom code at different points in the process - definition. To do this we have to specify an action handler, represented by an - implementation of the <emphasis> - <property>ActionHandler</property> - </emphasis> interface, and attach this piece of code to a particular event. These events - are amongst others, going over a transition, leaving or entering nodes, after and before - signalling. </para> - - <para> To make things a little bit more concrete, let&apos;s create a new class called <emphasis> - <property>HelloActionHandler</property>. - </emphasis> For that firstly we&apos;ll create a new package <emphasis> - <property>com.jbay.action</property> - </emphasis> in the <emphasis> - <property>src/java/main</property> - </emphasis> folder of our project. Then, we should call New Class Creation wizard as - usual by right-clicking and navigating <emphasis> - <property>New > Class</property>. - </emphasis> </para> - - <figure> - <title>Creating HelloActionHendler Class</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_1.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Notice that two first gaps have been filled automatically. Here, instead of <emphasis> - <property>Package</property> - </emphasis> option <emphasis> - <property>Enclose type</property> - </emphasis> option can be selected where a type in which to enclose a new class should - be specified.</para> - - <para>In our case, we leave everything as it is, just type <emphasis> - <property>HelloActionHandler</property> - </emphasis> as a name of new class and add <emphasis> - <property>org.jbpm.graph.ActionHendler</property> - </emphasis> interface as it&apos;s shown in the picture above.</para> - - <para>Thus, our <emphasis> - <property>HelloActionHandler</property> - </emphasis> implements the <emphasis> - <property>ActionHandler</property> - </emphasis> interface including the <emphasis> - <property>execute</property> - </emphasis> method as shown in the next figure. Here, we add a variable named <emphasis> - <property>greeting</property> - </emphasis> to the collection of process variables and put a message in it : - <emphasis>&quot;Hello from ActionHandler&quot;</emphasis>. </para> - - <figure> - <title>A Simple Hello Action</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_2.png" scale="75"/> - </imageobject> - </mediaobject> - </figure> - - <para>Now, as we have <emphasis> - <property>HelloActionHandler</property> - </emphasis> class defined, let&apos;s explore how we can handle it.</para> - </section> - - <section> - <title>Integrating the Hello World Action</title> - - <para>The main purpose of this chapter is to provide you with the steps associating our - Hello World action with a particular event and test the correctness of our actions as - well.</para> - - <para> As good Testcity citizens we will first create a Unit Test that proves the behaviour - we want to achieve by adding the <emphasis> - <property>ActionHandler</property> - </emphasis> to the process. So we implement another test.</para> - - <para>At first, let&apos;s return to the - code we already saw <link linkend="hello_test">in the previous chapter</link> and add new test method <emphasis> - <property>testActionHendler</property></emphasis> to it. </para> - - <figure> - <title>Create the Hello Action Test</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_3.png" - scale="75"/> - </imageobject> - </mediaobject> - </figure> - - <para>We assert - that no variable called <emphasis> - <property>greeting</property> - </emphasis> exist. Then we give the process a signal to move it to the auction state. We - want to associate the execution of the action with the event of going over the - transition from the start state to the auction state. So after the signal, the process - should be in the auction state as in the previous scenario. But moreover, the <emphasis> - <property>greeting</property> - </emphasis> variable should exist and contain the string <emphasis>&quot;Hello from - ActionHandler&quot;</emphasis>. That&apos;s what we assert in the last lines of the test - method.</para> - - - - <para> Running the tests now results in a failure. The point is that we did not associate - the action with any particular event in the process definition, so the process variable - did not get set. </para> - - <figure> - <title>Test Results Before Integration</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_4.png" - scale="75"/> - </imageobject> - </mediaobject> - </figure> - - <para> Let&apos;s do something about it and add an action to the first transition of our - sample process. To do this you can use the Actions tab in the Properties Editor that is - under the graphical canvas. Bring up the popup menu of the action element container and - chose New Action as it's shown on the figure below. The other way to add an action - to the transition is simply to use the dropdown menu that is available under the action - icon in the right upper corner of the Properties View.</para> - - <figure> - <title>Adding an Action to a Transition</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_5.png" scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>After adding the action a tabbed view with three pages will appear.</para> - - <figure> - <title>Configuration Dialog for an Action</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_6.png" scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>The first of these three pages allows you to give the Action a name. The last page - contains some advanced attributes such as whether the Action is asynchronous. The - Details page is the most important. It allows to choose and configure the actual action - handler implementation. </para> - - <figure> - <title>The Details page of an Action Configuration Dialog</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_7.png" scale="80"/> - </imageobject> - </mediaobject> - </figure> - - - <para>Clicking on the <emphasis> - <property>Search...</property> - </emphasis> button brings us to a Choose Class dialog.</para> - - - <figure> - <title>The Choose Action Handler Dialog</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_8.png"/> - </imageobject> - </mediaobject> - </figure> - - - <para> We choose our previously created &apos;HelloActionHandler&apos; class and - push the <property>OK</property> button. After the selection of the action handler for - the action, we can run the test and observe it gives us a green light.</para> - - <figure> - <title>Test Results</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_9.png" - scale="70"/> - </imageobject> - </mediaobject> - </figure> - - <para>There we are. The above objective has been achieved.</para> - </section> - - <section> - <title> Integration Points</title> - - <para> The different integration points in a process definition are thoroughly documented in - the <ulink - url="http://docs.jboss.com/jbpm/v3/userguide/">JBoss jBPM User Guide</ulink>. Instance nodes can contain many action - elements. Each of these will appear in the Action element list of the Actions tab. But - each Action also has a properties view of itself. You can navigate to this view by - selecting the added Action in the outline view. </para> - - </section> - </section> - <section id="Quick_Howto_Guide" xreflabel="Quick_Howto_Guide"> - <?dbhtml filename="Quick_Howto_Guide.html"?> - - <title>Quick Howto Guide</title> - - <para>This chapter contains additional information related to the <property>JBoss - jBPM</property>.</para> - - <section id="change_core_jbpm_inst"> - <title>Change the Default Core jBPM Installation</title> - - <para> You can change the default <property>jBPM</property> installation by means of the - Eclipse preference mechanism. Open the Preferences dialog by selecting <emphasis> - <property>Window &gt; Preferences</property> - </emphasis> and select the <emphasis> - <property>JBoss jBPM &gt; Runtime Location</property> - </emphasis> category. Using this page you can add multiple <property>jBPM</property> - installation locations and change the default one. The default installation is used for - the classpath settings when creating a new Process Project. Changing the preferences has - no influence on already created projects. Getting rid of a <property>jBPM</property> - installation that&apos;s being referenced by a project however will cause the - classpath to contain errors. </para> - - - <figure> - <title>The jBPM Preferences Page</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_1.png"/> - </imageobject> - </mediaobject> - </figure> - </section> - - <section> - <title>Configuring Task Nodes</title> - - <para>Here, we&apos;ll examine how you can configure the Task nodes in jBPM jPDL GPD.</para> - - <para> You can add Tasks to Task nodes and then configure them in a similar manner as the - Action configuration mechanism. Let&apos;s consider the process definition similar - to the previous one that contains three nodes: Start state, Task node and End state. The - <property>Properties view</property> for selected Task node includes several tabs. </para> - - <figure> - <title>The Properties View of the selected Task Node</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_2.png" - scale="75"/> - </imageobject> - </mediaobject> - </figure> - - <para>We should choose the Task tab and then bring up the context menu or click the button - in the top right corner of the view to add a Task to our Task node.</para> - - <figure> - <title>Adding a Task to the Task Node</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_3.png" - scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>Every added Task has its own configuration possibilities. You can access them through - the <property>Properties view</property> as well.</para> - - <figure> - <title>The Task properties</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_4.png" - scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>The <property>General page</property> is a place where you can specify the name of a - Task and its description. For instance, let it be <emphasis> - <property>approve oder</property> - </emphasis> with appropriate description that you can see in the figure below.</para> - - <figure> - <title>The Task General Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_5.png" - scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>Now, look at <property>Details page</property>. First, you should specify the due date - that is a mandatory property for the Task. The due date is the date on which the task - should be accomplished. Here you can also set a Task priority as well as signalling, - notifying or blocking. The <emphasis> - <property>Blocking</property> - </emphasis> attribute indicates that the process will not be able to continue if this - task is still unaccomplished. The <emphasis> - <property>Generate Form...</property> - </emphasis> button is for creating a simple task form that can be rendered by the jBPM - console.</para> - - <figure> - <title>The Task Details Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_6.png" - scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>For our example, we specify the due date as 2 business days, choose the high priority - and also check the <emphasis> - <property>Signalling</property> - </emphasis> and <emphasis> - <property>Notify</property> - </emphasis> attributes. It means that the Task should be accomplished in 2 business days - and the assignee will be notified by email when the task is assigned. To specify how the - Task should be assigned switch on to the <property>Assignment page</property>.</para> - - <figure> - <title>The Task Assignment Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_7.png" - scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>On the <property>Reminder page</property> you can specify whether the assignee will be reminded of the task - that awaits him.</para> - - <figure> - <title>The Task Reminder Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_8.png" - scale="80"/> - </imageobject> - </mediaobject> - </figure> - - <para>In our case, the assignee will be reminded by email after two business hours and - continue to get reminding every business hour after that.</para> - <para>In the next figure you can see our configuring generated into XML.</para> - <figure> - <title>The Task Reminder Page</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_9.png" - scale="80"/> - </imageobject> - </mediaobject> - </figure> - <para>We hope, our guide will help you to get started with the jPDL process language and jBPM - workflow on the whole. Besides, for additional information you are welcome on <ulink - url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... forum</ulink>.</para> - </section> - </section> - +<?xml version="1.0" encoding="UTF-8"?> +<chapter> + <?dbhtml filename="jboss_jbpm_runtime_installation.html"?> + <chapterinfo> + <keywordset> + <keyword>jBPM</keyword> + <keyword>designer</keyword> + <keyword>process</keyword> + <keyword>JBoss Developer Studio</keyword> + <keyword>jBPM runtime</keyword> + <keyword>JBoss</keyword> + <keyword>Process</keyword> + <keyword>Definition</keyword> + </keywordset> + + </chapterinfo> + <title>Tasks</title> +<section id="jboss_jbpm_runtime_installation" xreflabel="jboss_jbpm_runtime_installation"> + + <title>JBoss jBPM Runtime Installation</title> + <para>The main purpose of this chapter is to let you know how to launch the <property>JBoss + jBPM</property> (business process management).</para> + <para>The jBPM plugin (jBPM Designer) is already included into the <property>JBoss Tools</property>. + To make it work, you should only download the jBPM runtime (<ulink + url="http://sourceforge.net/project/showfiles.php?group_id=70542&... + >jbpm-jpdl-3.2.3</ulink> currently) and specify the directory where you extracted the runtime + either when you create a jBPM project or by using the jBPM preference pages.</para> + + <note> + <title>Note:</title> + <para>Try to avoid using spaces in the names of installation folders. It can provoke problems in + some situations with Sun-based VMs.</para> + </note> + + <para>Navigate to <emphasis> + <property>Window &gt; Preferences &gt; JBoss jBPM &gt; Runtime Locations</property>. + </emphasis> Here you can add, edit and remove JBoss jBPM installation locations. Click <emphasis> + <property>Add</property> + </emphasis> button. In the dialog that appeared enter a name for a newly added jBPM runtime and + point to the correct location of this package on your harddrive. Click <emphasis> + <property>OK</property> + </emphasis> then click <emphasis> + <property>OK</property> + </emphasis> again.</para> + + <figure> + <title>Adding jBPM Location</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtime_installation/runtime_installation_1.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Now, when you have a runtime installed, we are going to demonstrate some powerful features of + the jBPM.</para> +</section> + <section id="GuidedTourJBossjBPMGPD" xreflabel="GuidedTourJBossjBPMGPD"> + <?dbhtml filename="GuidedTourJBossjBPMGPD.html"?> + + <title>A Guided Tour of JBoss jBPM GPD</title> + <para>In this chapter we suggest a step-by-step walk-through of creating and configuring your + own simple process. Let's try to organize a new jBPM project.</para> + <para>A wizard for creating a jBPM project is included in the GPD plugin. We have opted to + create a project based on a template already containing a number of advanced artifacts that + we will ignore for this section. In the future we will elaborate this wizard and offer the + possibility to create an empty jBPM project as well as projects based on templates taken + from the jBPM tutorial.</para> + <section id="CreatingjBPMProject"> + <?dbhtml filename="CreatingjBPMProject.html"?> + <title>Creating a jBPM Project</title> + <para>This section will show you how to use the Creation wizard for creating a new jBPM + project with already included source folders.</para> + <para>At first you should select <emphasis> + <property>File &gt;New Project...</property> + </emphasis> and then <emphasis> + <property>JBoss jBPM &gt; Process Project</property> + </emphasis> in the New Project dialog:</para> + <figure> + <title>New Project Dialog</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_1.png"/> + </imageobject> + </mediaobject> + </figure> + <para> Clicking <emphasis> + <property>Next</property> + </emphasis> brings us to the wizard page where it&apos;s necessary to specify the + name and location for the project. We choose, for example, <emphasis> + <property>HellojBPM</property> + </emphasis> as the name and accept the default location. </para> + <figure> + <title>Process Name and Location</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_2.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Thus, our project will be created in the workspace root directory by default. If you + want to change the directory for your future project, deselect <emphasis> + <property>Use default location</property> + </emphasis> and click <emphasis> + <property>Browse...</property> + </emphasis> button to set needed location or simply type it.</para> + <para>On the next screen you&apos;ll be prompted to select the core jBPM location that + we have defined in the previous chapter.</para> + <figure> + <title>Core jBPM Location Specifying</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_9.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Clicking on <emphasis> + <property>Finish</property> + </emphasis> results in the project being generated. The wizard creates four source + folders: one for the processes (<emphasis> + <property>src/main/jpdl</property> + </emphasis>), one for the java sources (<emphasis> + <property>src/main/java</property> + </emphasis>), one for the unit tests (<emphasis> + <property>src/test/java</property> + </emphasis>) and one for the resources such as the jbpm.properties and the + hibernate.properties files (<emphasis> + <property>src/main/config</property> + </emphasis>). In addition a classpath container with all the core jBPM libraries is + added to the project</para> + <figure> + <title>Layout of the Process Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_3.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Looking inside the different source folders will reveal a number of other artifacts + that were generated, but we will leave these untouched for the moment. Instead, we will + look at another wizard that enables us to create an empty process definition.</para> + </section> + <section id="creating_an_empty_process_definition"> + <?dbhtml filename="creating_an_empty_process_definition.html"?> + <title>Creating an Empty Process Definition</title> + <para>Now when the project is set up, we can use a Creation wizard to create an empty + process definition. Bring up the <emphasis> + <property>New</property> + </emphasis> wizard by clicking the <emphasis> + <property>File &gt; New &gt; Other...</property> + </emphasis> menu item. The wizard opens on the <emphasis> + <property>Select Wizard</property> + </emphasis> page.</para> + <figure> + <title>The Select Wizard Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_4.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Selecting the <emphasis> + <property>JBoss jBPM</property> + </emphasis> category, then the <emphasis> + <property>Process Definition</property> + </emphasis> item and clicking on the <emphasis> + <property>Next</property> + </emphasis> button brings us to the <emphasis> + <property>Create Process Definition</property> + </emphasis> page.</para> + <figure> + <title>The Create New Process Defining Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_5.png"/> + </imageobject> + </mediaobject> + </figure> + <para>We choose <emphasis> + <property>hello</property> + </emphasis> as the name of the process archive file. Click on the <emphasis> + <property>Finish</property> + </emphasis> button to end the wizard and open the process definition editor.</para> + <figure> + <title>The Process Definition Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_6.png" + scale="60"/> + </imageobject> + </mediaobject> + </figure> + + + <para>You can see in the Package Explorer that creating a process definition involves + creating a folder with the name of the process definition and populating this folder + with two .xml files : <emphasis> + <property>gpd.xml</property> + </emphasis> , <emphasis> + <property>processdefinition.xml</property> </emphasis> and a .jpg file:<emphasis> + <property>processimage.jpg</property></emphasis>.</para> + <para>The <emphasis> + <property>gpd.xml</property> + </emphasis> contains the graphical information used by the process definition editor. + The <emphasis> + <property>processdefinition.xml</property> + </emphasis> file contains the actual process definition info. + The graphical view of the process is automatically saved in <emphasis> + <property>processimage.jpg</property> + </emphasis>file. + At present, the GPD assumes that these three files are siblings. More + sophisticated configuration will be supported later.</para> + + <section id="minimal_process_definition"> + <?dbhtml filename="minimal_process_definition.html"?> + <title>A Minimal Process Definition</title> + <para>Now we are ready to create a very simple process definition consisting of a begin + state, an intermediate state and an end state.</para> + <para>To make the configuration of actions much easier it&apos;s better to use the + <emphasis>><property>"jBPM jPDL 3"</property></emphasis> perspective. It provides the tabbed Properties Editor which allows to configure + all the relevant properties of the current selected item. </para> + + <section id="adding_the_nodes"> + <?dbhtml filename="adding_the_nodes.html"?> + <title>Adding the Nodes</title> + <para>At first select respectively <emphasis> + <property>Start</property>, </emphasis> + <emphasis> + <property>State</property> + </emphasis> and <emphasis> + <property>End</property> + </emphasis> on the tools palette and click on the canvas to add these nodes to + the process definition. The result should look similar to this:</para> + <figure> + <title>A Simple Process With Three Nodes</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_7.png" + scale="60"/> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="adding_transitions"> + <?dbhtml filename="adding_transitions.html"?> + <title>Adding Transitions</title> + <para>Then, we will connect the nodes with transitions. To do that select the <emphasis> + <property>Transition</property> + </emphasis> tool in the tools palette and click on the <emphasis> + <property>Start</property> + </emphasis> node, then move to the <emphasis> + <property>State</property> + </emphasis> node and click again to see the transition being drawn. Perform the + same steps to create a transition from the <emphasis> + <property>State</property> + </emphasis> node to the <emphasis> + <property>End</property> + </emphasis> node. The result will look like:</para> + <figure> + <title>A Simple Process With Transitions</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/guided_tour_jboss_jbpmgpd/guided_tour_8.png" + scale="60"/> + </imageobject> + </mediaobject> + </figure> + <para>Now, when you&apos;ve got background knowledge of simple project creation, + let&apos;s move to more advanced tools.</para> + </section> + </section> + </section> + </section> + <section id="The_JBoss_jBPM_Int_Mech" xreflabel="The_JBoss_jBPM_Int_Mech"> + <?dbhtml filename="The_JBoss_jBPM_Int_Mech.html"?> + + <title>Actions : The JBoss jBPM Integration Mechanism</title> + + <para> In this chapter we will show how to do software integration with <property>JBoss + jBPM</property>. The standard mechanism to implement this is to wrap the functionality you + want to integrate in a class that implements the <emphasis> + <property>ActionHandler</property> + </emphasis> interface. In order to demonstrate it let's specify Hello World action for our + process.</para> + + <section> + <title>Creating a Hello World Action</title> + + <para>Each Hello World process should integrate one or more Hello World actions, so this is + what we will be doing. We can integrate custom code at different points in the process + definition. To do this we have to specify an action handler, represented by an + implementation of the <emphasis> + <property>ActionHandler</property> + </emphasis> interface, and attach this piece of code to a particular event. These events + are amongst others, going over a transition, leaving or entering nodes, after and before + signalling. </para> + + <para> To make things a little bit more concrete, let&apos;s create a new class called <emphasis> + <property>HelloActionHandler</property>. + </emphasis> For that firstly we&apos;ll create a new package <emphasis> + <property>com.jbay.action</property> + </emphasis> in the <emphasis> + <property>src/java/main</property> + </emphasis> folder of our project. Then, we should call New Class Creation wizard as + usual by right-clicking and navigating <emphasis> + <property>New > Class</property>. + </emphasis> </para> + + <figure> + <title>Creating HelloActionHendler Class</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_1.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Notice that two first gaps have been filled automatically. Here, instead of <emphasis> + <property>Package</property> + </emphasis> option <emphasis> + <property>Enclose type</property> + </emphasis> option can be selected where a type in which to enclose a new class should + be specified.</para> + + <para>In our case, we leave everything as it is, just type <emphasis> + <property>HelloActionHandler</property> + </emphasis> as a name of new class and add <emphasis> + <property>org.jbpm.graph.ActionHendler</property> + </emphasis> interface as it&apos;s shown in the picture above.</para> + + <para>Thus, our <emphasis> + <property>HelloActionHandler</property> + </emphasis> implements the <emphasis> + <property>ActionHandler</property> + </emphasis> interface including the <emphasis> + <property>execute</property> + </emphasis> method as shown in the next figure. Here, we add a variable named <emphasis> + <property>greeting</property> + </emphasis> to the collection of process variables and put a message in it : + <emphasis>&quot;Hello from ActionHandler&quot;</emphasis>. </para> + + <figure> + <title>A Simple Hello Action</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_2.png" scale="75"/> + </imageobject> + </mediaobject> + </figure> + + <para>Now, as we have <emphasis> + <property>HelloActionHandler</property> + </emphasis> class defined, let&apos;s explore how we can handle it.</para> + </section> + + <section> + <title>Integrating the Hello World Action</title> + + <para>The main purpose of this chapter is to provide you with the steps associating our + Hello World action with a particular event and test the correctness of our actions as + well.</para> + + <para> As good Testcity citizens we will first create a Unit Test that proves the behaviour + we want to achieve by adding the <emphasis> + <property>ActionHandler</property> + </emphasis> to the process. So we implement another test.</para> + + <para>At first, let&apos;s return to the + code we already saw <link linkend="hello_test">in the previous chapter</link> and add new test method <emphasis> + <property>testActionHendler</property></emphasis> to it. </para> + + <figure> + <title>Create the Hello Action Test</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_3.png" + scale="75"/> + </imageobject> + </mediaobject> + </figure> + + <para>We assert + that no variable called <emphasis> + <property>greeting</property> + </emphasis> exist. Then we give the process a signal to move it to the auction state. We + want to associate the execution of the action with the event of going over the + transition from the start state to the auction state. So after the signal, the process + should be in the auction state as in the previous scenario. But moreover, the <emphasis> + <property>greeting</property> + </emphasis> variable should exist and contain the string <emphasis>&quot;Hello from + ActionHandler&quot;</emphasis>. That&apos;s what we assert in the last lines of the test + method.</para> + + + + <para> Running the tests now results in a failure. The point is that we did not associate + the action with any particular event in the process definition, so the process variable + did not get set. </para> + + <figure> + <title>Test Results Before Integration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_4.png" + scale="75"/> + </imageobject> + </mediaobject> + </figure> + + <para> Let&apos;s do something about it and add an action to the first transition of our + sample process. To do this you can use the Actions tab in the Properties Editor that is + under the graphical canvas. Bring up the popup menu of the action element container and + chose New Action as it's shown on the figure below. The other way to add an action + to the transition is simply to use the dropdown menu that is available under the action + icon in the right upper corner of the Properties View.</para> + + <figure> + <title>Adding an Action to a Transition</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_5.png" scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>After adding the action a tabbed view with three pages will appear.</para> + + <figure> + <title>Configuration Dialog for an Action</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_6.png" scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>The first of these three pages allows you to give the Action a name. The last page + contains some advanced attributes such as whether the Action is asynchronous. The + Details page is the most important. It allows to choose and configure the actual action + handler implementation. </para> + + <figure> + <title>The Details page of an Action Configuration Dialog</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_7.png" scale="80"/> + </imageobject> + </mediaobject> + </figure> + + + <para>Clicking on the <emphasis> + <property>Search...</property> + </emphasis> button brings us to a Choose Class dialog.</para> + + + <figure> + <title>The Choose Action Handler Dialog</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_8.png"/> + </imageobject> + </mediaobject> + </figure> + + + <para> We choose our previously created &apos;HelloActionHandler&apos; class and + push the <property>OK</property> button. After the selection of the action handler for + the action, we can run the test and observe it gives us a green light.</para> + + <figure> + <title>Test Results</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/The_JBoss_jBPM_Int_Mech/jboss_jbpm_int_mech_9.png" + scale="70"/> + </imageobject> + </mediaobject> + </figure> + + <para>There we are. The above objective has been achieved.</para> + </section> + + <section> + <title> Integration Points</title> + + <para> The different integration points in a process definition are thoroughly documented in + the <ulink + url="http://docs.jboss.com/jbpm/v3/userguide/">JBoss jBPM User Guide</ulink>. Instance nodes can contain many action + elements. Each of these will appear in the Action element list of the Actions tab. But + each Action also has a properties view of itself. You can navigate to this view by + selecting the added Action in the outline view. </para> + + </section> + </section> + <section id="Quick_Howto_Guide" xreflabel="Quick_Howto_Guide"> + <?dbhtml filename="Quick_Howto_Guide.html"?> + + <title>Quick Howto Guide</title> + + <para>This chapter contains additional information related to the <property>JBoss + jBPM</property>.</para> + + <section id="change_core_jbpm_inst"> + <title>Change the Default Core jBPM Installation</title> + + <para> You can change the default <property>jBPM</property> installation by means of the + Eclipse preference mechanism. Open the Preferences dialog by selecting <emphasis> + <property>Window &gt; Preferences</property> + </emphasis> and select the <emphasis> + <property>JBoss jBPM &gt; Runtime Location</property> + </emphasis> category. Using this page you can add multiple <property>jBPM</property> + installation locations and change the default one. The default installation is used for + the classpath settings when creating a new Process Project. Changing the preferences has + no influence on already created projects. Getting rid of a <property>jBPM</property> + installation that&apos;s being referenced by a project however will cause the + classpath to contain errors. </para> + + + <figure> + <title>The jBPM Preferences Page</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_1.png"/> + </imageobject> + </mediaobject> + </figure> + </section> + + <section> + <title>Configuring Task Nodes</title> + + <para>Here, we&apos;ll examine how you can configure the Task nodes in jBPM jPDL GPD.</para> + + <para> You can add Tasks to Task nodes and then configure them in a similar manner as the + Action configuration mechanism. Let&apos;s consider the process definition similar + to the previous one that contains three nodes: Start state, Task node and End state. The + <property>Properties view</property> for selected Task node includes several tabs. </para> + + <figure> + <title>The Properties View of the selected Task Node</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_2.png" + scale="75"/> + </imageobject> + </mediaobject> + </figure> + + <para>We should choose the Task tab and then bring up the context menu or click the button + in the top right corner of the view to add a Task to our Task node.</para> + + <figure> + <title>Adding a Task to the Task Node</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_3.png" + scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>Every added Task has its own configuration possibilities. You can access them through + the <property>Properties view</property> as well.</para> + + <figure> + <title>The Task properties</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_4.png" + scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>The <property>General page</property> is a place where you can specify the name of a + Task and its description. For instance, let it be <emphasis> + <property>approve oder</property> + </emphasis> with appropriate description that you can see in the figure below.</para> + + <figure> + <title>The Task General Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_5.png" + scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>Now, look at <property>Details page</property>. First, you should specify the due date + that is a mandatory property for the Task. The due date is the date on which the task + should be accomplished. Here you can also set a Task priority as well as signalling, + notifying or blocking. The <emphasis> + <property>Blocking</property> + </emphasis> attribute indicates that the process will not be able to continue if this + task is still unaccomplished. The <emphasis> + <property>Generate Form...</property> + </emphasis> button is for creating a simple task form that can be rendered by the jBPM + console.</para> + + <figure> + <title>The Task Details Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_6.png" + scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>For our example, we specify the due date as 2 business days, choose the high priority + and also check the <emphasis> + <property>Signalling</property> + </emphasis> and <emphasis> + <property>Notify</property> + </emphasis> attributes. It means that the Task should be accomplished in 2 business days + and the assignee will be notified by email when the task is assigned. To specify how the + Task should be assigned switch on to the <property>Assignment page</property>.</para> + + <figure> + <title>The Task Assignment Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_7.png" + scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>On the <property>Reminder page</property> you can specify whether the assignee will be reminded of the task + that awaits him.</para> + + <figure> + <title>The Task Reminder Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_8.png" + scale="80"/> + </imageobject> + </mediaobject> + </figure> + + <para>In our case, the assignee will be reminded by email after two business hours and + continue to get reminding every business hour after that.</para> + <para>In the next figure you can see our configuring generated into XML.</para> + <figure> + <title>The Task Reminder Page</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/Quick_Howto_Guide/quick_howto_guide_9.png" + scale="80"/> + </imageobject> + </mediaobject> + </figure> + <para>We hope, our guide will help you to get started with the jPDL process language and jBPM + workflow on the whole. Besides, for additional information you are welcome on <ulink + url="http://www.jboss.com/index.html?module=bb&amp;op=viewforum&... forum</ulink>.</para> + </section> + </section> + </chapter> \ No newline at end of file