From jbosstools-commits at lists.jboss.org Thu Jan 29 12:35:00 2009 Content-Type: multipart/mixed; boundary="===============0563809164492497902==" MIME-Version: 1.0 From: jbosstools-commits at lists.jboss.org To: jbosstools-commits at lists.jboss.org Subject: [jbosstools-commits] JBoss Tools SVN: r13340 - branches/jbosstools-3.0.0.CR2/jbpm/docs/reference/en. Date: Thu, 29 Jan 2009 12:35:00 -0500 Message-ID: --===============0563809164492497902== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: ochikvina Date: 2009-01-29 12:35:00 -0500 (Thu, 29 Jan 2009) New Revision: 13340 Added: branches/jbosstools-3.0.0.CR2/jbpm/docs/reference/en/master_output.xml Log: https://jira.jboss.org/jira/browse/JBDS-571- adding the master_output.xml; Added: branches/jbosstools-3.0.0.CR2/jbpm/docs/reference/en/master_output.x= ml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- branches/jbosstools-3.0.0.CR2/jbpm/docs/reference/en/master_output.xml = (rev 0) +++ branches/jbosstools-3.0.0.CR2/jbpm/docs/reference/en/master_output.xml = 2009-01-29 17:35:00 UTC (rev 13340) @@ -0,0 +1,1288 @@ + + + + + + + + + + + + + + + + + + + + = + + ]> + + jBPM Tools Reference Guide + + + Anatoly + Fedosik + + + Koen + Aers + koen.aers(a)jboss.com + + + Olga + Chikvina + + + Svetlana + Mukhina + smukhina(a)exadel.com + + + Tom + Baeyens + tom.baeyens(a)jboss.com + + + + April 2008 + + 2007 + 2008 + JBoss, a division of Red Hat Inc. + + Version: 3= .1.5.CR1 + + + + + PDF version + + + + + = + + = + + + + + jBPM + Target + developers + Audience + + + Introduction + All developers and process analysts who are beginning to use JBoss = jBPM should read this + Getting Started guide. It will give them a jumpstart showing how to crea= te a process definition. +
+ + Preface + This document introduces the use of the JBoss jBPM Graphical Proce= ss Designer (GPD) to + create workflow processes. It will help first time users with the follo= wing tasks : + + + Install the JBoss jBPM GPD Eclipse plugin available from the JBo= ss jBPM download + area + + + Set up a Java project in Eclipse and prepare it to do test drive= n process + development + + + Using the creation wizard to create an empty process definition<= /para> + + + Use the designer palette to draw the first processdefinition + + + Show how the xml processdefinition can be inspected as an xml fi= le + + + Set up a Java project in Eclipse and prepare it to do test drive= n process + development + + + Write an example process test case + + + If you have questions, please feel free to contact Koen Aers or Tom Baeyens for more + information. +
+ +
+ + Feature list + + JBoss jBPM is a workflow that enables creating and automatization= business processes. Look + at the list of features below to understand its main functionality. + + Key Functionality for JBoss jBPM + + + + Feature + Benefit + + + + + + + jBDL support + + Enables managing workflow processes as well as human tasks an= d interactions between + them. jBDL combines the best both Java and declarative process tech= niques. + + + + + Support of Graphical Proce= ss Designer (GPD) + + Is used for simplifying declarative process development and v= isualizations of all + actions. + + + + + Project Creation wizard + + Allows to create a new jBPM template project that already inc= ludes all advanced + artifacts and core jBPM libraries. + + + + + Rich palette of pre-bu= ild process nodes + + Provides process-building functionality and gives opportunity= even non-programmers to + develop processes. + + + + + Support of XML code view + + Shows the corresponding XML that's generated automatically in= the Source view + of the process definition editor when developing the process. + + + + + Properties view + + Facilitates configuring and editing of all nodes properties.<= /entry> + + + + Interaction with all of the J2EE based integration technologi= es including Web Services, + Java Messaging, J2EE Connectors, JBDC, EJBs. + Enables implementation, provides better functionality and fle= xibility. + + + + Integration with jBoss Seam + Allows to write applications with complex workflows and provi= des easier interactions + between them. + + + + +
+
+ = +
+ Other relevant resources on the topic + All JBoss Developer Studio/JBoss Tools documentation you can find = here. + The latest documentation builds are available here. +
+ + + = + = + + + + + jBPM + designer + process + JBoss Developer Studio + jBPM runtime + + + JBoss jBPM Runtime Installation + The main purpose of this chapter is to let you know how to launch t= he JBoss + jBPM (business process management). + The jBPM plugin (jBPM Designer) is already included in the JBoss Tools. + To make it work, you should only download the jBPM runtime (jbpm-jpdl-3.2.2 currently)= and specify the directory where you extracted the runtime + either when you create a jBPM project or by using the jBPM preference pa= ges. + + + Note: + Try to avoid using spaces in the names of installation folders. It= can provoke problems in + some situations with Sun-based VMs. + + + Navigate to + Window > Preferences > JBoss jBPM >= ; Runtime Locations. + Here you can add, edit and remove JBoss jBPM installation lo= cations. Click + Add + 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> + OK + then click + OK + again. + +
+ Adding jBPM Location + + + + + +
+ Now, when you have a runtime installed, we are going to demonstrate= some powerful features of + the jBPM. + + = + = + + + + + jBPM + JBoss + Process + Definition + + + A Guided Tour of JBoss jBPM GPD + 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. + 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 adva= nced artifacts that + we will ignore for this section. In the future we will elaborate this wi= zard and offer the + possibility to create an empty jBPM project as well as projects based on= templates taken + from the jBPM tutorial. +
+ + Creating a jBPM Project + This section will show you how to use the Creation wizard for crea= ting a new jBPM + project with already included source folders. + At first you should select + File >New Project... + and then + JBoss jBPM > Process Project + in the New Project dialog: +
+ New Project Dialog + + + + + +
+ Clicking + Next + brings us to the wizard page where it's necessary to specif= y the + name and location for the project. We choose, for example, + HellojBPM + as the name and accept the default location. +
+ Process Name and Location + + + + + +
+ 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 + Use default location + and click + Browse... + button to set needed location or simply type it. + On the next screen you'll be prompted to select the core jBPM loca= tion that + we have defined in the previous chapter. +
+ Core jBPM Location Specifying + + + + + +
+ Clicking on + Finish + results in the project being generated. The wizard creates = four source + folders: one for the processes ( + src/main/jpdl + ), one for the java sources ( + src/main/java + ), one for the unit tests ( + src/test/java + ) and one for the resources such as the jbpm.properties and = the + hibernate.properties files ( + src/main/config + ). In addition a classpath container with all the core jBPM = libraries is + added to the project +
+ Layout of the Process Project + + + + + +
+ Looking inside the different source folders will reveal a number o= f 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 defin= ition. +
+
+ + Creating an Empty Process Definition + Now when the project is set up, we can use a Creation wizard to cr= eate an empty + process definition. Bring up the + New + wizard by clicking the + File > New > Other... + menu item. The wizard opens on the + Select Wizard + page. +
+ The Select Wizard Page + + + + + +
+ Selecting the + JBoss jBPM + category, then the + Process Definition + item and clicking on the + Next + button brings us to the + Create Process Definition + page. +
+ The Create New Process Definion Page + + + + + +
+ We choose + hello + as the name of the process archive file. Click on the + Finish + button to end the wizard and open the process definition ed= itor. +
+ The Process Definition Editor + + + + + +
+ + + You can see in the Package Explorer that creating a process defini= tion involves + creating a folder with the name of the process definition and populatin= g this folder + with two .xml files : + gpd.xml + and + processdefinition.xml. + The + gpd.xml + contains the graphical information used by the process defi= nition editor. + The + processdefinition.xml + file contains the actual process definition info without th= e graphical + rendering info. At present, the GPD assumes that these two files are si= blings. More + sophisticated configuration will be supported later. + +
+ + A Minimal Process Definition + Now we are ready to create a very simple process definition consi= sting of a begin + state, an intermediate state and an end state. + To make the configuration of actions much easier it's better to u= se the + jPDL perspective. It provides the tabbed Properties Editor which allow= s to configure + all the relevant properties of the current selected item. + +
+ + Adding the Nodes + At first select respectively + Start, + + State + and + End + on the tools palette and click on the canvas to add these= nodes to + the process definition. The result should look similar to this: +
+ A Simple Process With Three Nodes + + + + + +
+
+
+ + Adding Transitions + Then, we will connect the nodes with transitions. To do that sel= ect the + Transition + tool in the tools palette and click on the + Start + node, then move to the + State + node and click again to see the transition being drawn. P= erform the + same steps to create a transition from the + State + node to the + End + node. The result will look like: +
+ A Simple Process With Transitions + + + + + +
+ Now, when you've got background knowledge of simple project crea= tion, + let's move to more advanced tools. +
+
+
+ + + + = + + + + + jBPM + + + + The views + + Here, it will be explained how to work with views and editors pr= ovided by JBDS. + The views are used for representation and navigation the resourc= es you are working on at + the moment. One of the advantages of all the views is that all mod= ifications made in the + currant-active file are immediately displayed in them. Let=E2=80= =99s get acquainted more closely + with those that the jPDL perspective provides. + +
+ The jPDL Perspective Views and Editors + + + + + +
+ + As you can see in the picture above, the jPDL perspective contains a + complete set of functionality that's necessary for working on the = jBPM project. + +
+ + The Outline View + To have a way to quickly see an outline of the process use t= he + Outline view + that is presented as the classical tree. If it is = not visible select + Window > Show view > Out= line. + +
+ The Overview View + + + + + +
+
+ +
+ + The Overview + The main advantage of this view is that it gives visual repr= esentation of the whole + currant-developing process. Besides, the + Overview + comes as a scrollable thumbnail which enables a be= tter navigation of the + process structure if it's too large. + +
+ The Overview + + + + + +
+
+ +
+ + The Properties View + Here, we dwell on the JBDS Prop= erties view. + Notice if it's not visible you can access it by navigating <= emphasis> + Window > Show view > Pro= perties. + The view shows the relevant properties of the selected item = in the tabbed form. Every + item has its own set of properties, which can be directly edit= able in the Properties + view or by brining up the context menu. + +
+ The Properties View of selected Transition + + + + + +
+ + For example, on the picture above the Properties view displa= ys all the properties for + a selected transition. Its name has been changed to + to_auction. We've done it directly in + active General tab of the view. The same way let's change the = name for the + second transition to + to_end. = + If no one item is selected, the view represents the properti= es of the whole process + definition. + +
+ The Properties View of Process Definition + + + + + +
+ + In this case, it contains six tabs. The first one is the + General.= It allows to specify a process name and add + necessary description. To illustrate let's change the process = definition name + to + jbay. +
+ +
+ + The jBPM Graphical Process Designer editor. + The jBPM GPD editor i= ncludes four modes: Diagram, Deployment, + Design and Source, which are available as switchable tabs at t= he bottom of the editor. + Let's dwell on each of them. + +
+ The Diagram mode + In this mode we define the process in the form of a dia= gram by means of tools + provided on the left-hand side of the jBPM GPD. + +
+ The Diagram mode + + + + + +
+ + Besides, some properties can be directly edited in the <= property moreinfo=3D"none">Diagram + mode of the graphical editor. One example of th= is is the + name + property of nodes. You can edit this directly = by selecting the node of + which you want to change the name and then click once insi= de this node. This enables + an editor in the node. We change the name of the node to <= emphasis> + auction. +
+ +
+ + The Source Mode + Now, that we have defined a simple process definition, w= e can have a look at the + XML that is being generated under the covers. To see this = XML click on the Source + tab of the graphical process designer editor. + +
+ The Source Mode + + + + + +
+ The Source mode e= nables to easily manipulate our XML. That is + manually inserting and editing necessary elements or attri= butes. In addition, here + you can take advantage of content assist. +
+ +
+ + The Design Mode + One more way to edit your file is to use Design mode. You can + see it in the next picture: +
+ The Design Mode + + + + + +
+ + As you can see above, this mode looks like a table in th= e first column of which + the process structure is performed. Here, you can also ins= ert, remove and edit + elements or attributes, moreover add comments and instruct= ions. Their values can be + directly edited in the second column of the Design mode ta= ble. + For instance, let=E2=80=99s add a comment on the second = transition. For that, you should + bring up the context menu for it and choose + Add Before > Comment. + +
+ Adding a Comment + + + + + +
+ Then, we can put the text This transition lead= s to the end + state in the right column as its value. + +
+ Comment is added + + + + + +
+ +
+ +
+ + The Deployment Mode + Finally, to adjust the deployment settings of the projec= t you should switch on to + the tab that opens the Deploym= ent mode. On the picture below + the Deployment mode= is performed with default settings. Here, + you can easily modify them or, if the settings won't match= your needs, to + reset defaults. +
+ The Deployment Mode + + + + + +
+ + The button + Test Connections + is necessary to make sure whether all your set= tings are valid before + deploying the process. + Now that we've seen how to work with jPDL + perspective, let's pass on to the project testi= ng. +
+
+ + = + + + + + jBPM + + + + + + + Test Driven Process Development + + One of the most important advantages of JBoss jBPM's lightweigh= t approach to BPM + and workflow management is that developers can easily leverage the= ir usual programming + skills and techniques. One of these well-known techniques is Unit = Testing and Test Driven + Development. + In this chapter we will show how developers, making use of the J= Boss jBPM GPD, can use a + technique we have baptized Test Driven= Process Development to create + process definitions and test their correctness. + + When creating the + HellojBPM + project the Project Creation wizard has already put in= place all the library + requirements we need to start writing the jBPM unit tests. They ar= e contained in the jBPM + Library container and the most important of them is the + .jar + file containing the core jBPM classes. While working o= n the project you could + find them all in the Package Explorer<= /property>. + +
+ The jBPM Libraries + + + + + + +
+ + It must be noted that it is possible to change the location of t= he core jBPM installation + by changing the preference settings. More on this see + later in this book. + + With that extra knowledge on the project settings, you can crea= te your first test. To do + this, we create the + com.jbay + package in the + test/java + source folder. Then we bring up the context menu on th= is package and select + New > Other... + + +
+ Call the JUnit Test Case Creation wizard + + + + + + +
+ + And then + Java > JUnit > JUnit Test Ca= se + to call the specialized JUnite Test case creation wiza= rd. +
+ Call the JUnit Test Case Creation wizard + + + + + + +
+ + The wizard looks as follows: + +
+ Create Test Dialog + + + + + + +
+ + By default JUnite 3 version of testing framework is selected. Of= course, you can choose + new advanced JUnit 4 version. In this case you'll be prompted to a= dd new JUnit + Library to your build path. To add it automatically just click on = the appropriate link. In + the + Class under test + section you can specify the class to test. + +
+ A First Test Scenario + + + + + + +
+ + Then, we call the test class + HelloTest + and press + Finish + button to complete. + + Next, we should write a simple test scenario as shown on the ne= xt figure. Let's + study the code of this test case. + +
+ A First Test Scenario + + + + + + +
+ + In the first line of the method, a jBPM process archive object i= s created. We use a + constructor accepting the filename of the archive. In our case it = is the + hello + file we created earlier and which lives in the + src/main/jpdl + folder of our project. After asserting that this objec= t is really created, we + extract a process definition object from it. This object is fed to= the constructor of a + process instance object. We have a process instance object, but th= is process is not yet + started, so we can safely assert that its root token still resides= in the start node. After + signalling the token will move to the next state and the process w= ill be in the + auction + state. Finally another signal will end the process. + + + After writing this test we can check whether it works as expect= ed by running it . + +
+ Running the Process Test + + + + + + +
+ All went well as we have a green light: + +
+ Successful Test Run + + + + + + +
+ + Of course, this simple scenario was not very interesting, but t= he purpose of it was to + show how you can reuse your development skills in a very straightf= orward way when doing + process development. To see how more interesting processes and pro= cess test + scenario's can be developed, we suggest you to read the JBoss jBPM User Guide= and to + study the API reference. You can find it in the jBPM download fold= er. (To get started we + downloaded jbpm-jpdl-3.2.2 in the second + chapter. You should just remember where you extracted i= t.) All we've mentioned are in the 'javadoc- *' subfolders of the 'doc' fol= der. + Moreover, some more examples will be given later in this book. + + + + = + + + + + jBPM + + + + + + + Actions : The JBoss jBPM Integration Mechanism + + In this chapter we will show how to do software integration wit= h JBoss + jBPM. The standard mechanism to implement this is to wr= ap the functionality you + want to integrate in a class that implements the + ActionHandler + interface. In order to demonstrate it let's specify He= llo World action for our + process. + +
+ Creating a Hello World Action + + 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 differe= nt points in the process + definition. To do this we have to specify an action handler, r= epresented by an + implementation of the + ActionHandler + interface, and attach this piece of code to a part= icular event. These events + are amongst others, going over a transition, leaving or enteri= ng nodes, after and before + signalling. + + To make things a little bit more concrete, let's create a n= ew class called + HelloActionHandler. + For that firstly we'll create a new package + com.jbay.action + in the + src/java/main + folder of our project. Then, we should call New Cl= ass Creation wizard as + usual by right-clicking and navigating + New > Class. + + +
+ Creating HelloActionHendler Class + + + + + + +
+ + Notice that two first gaps have been filled automatically. H= ere, instead of + Package + option + Enclose type + option can be selected where a type in which to en= close a new class should + be specified. + + In our case, we leave everything as it is, just type + HelloActionHandler + as a name of new class and add + org.jbpm.graph.ActionHendler + interface as it's shown in the picture above. + + Thus, our + HelloActionHandler + implements the + ActionHandler + interface including the + execute + method as shown in the next figure. Here, we add a= variable named + greeting + to the collection of process variables and put = a message in it : + "Hello from ActionHandler". + +
+ A Simple Hello Action + + + + + + +
+ + Now, as we have + HelloActionHandler + class defined, let's explore how we can handle it.= +
+ +
+ Integrating the Hello World Action + + 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 correc= tness of our actions as + well. + + As good Testcity citizens we will first create a Unit Test = that proves the behaviour + we want to achieve by adding the + ActionHandler + to the process. So we implement another test. + = + At first, let's return to the + code we already saw in the pre= vious chapter and add new test method + testActionHendler to it. + = +
+ Create the Hello Action Test + = + + + + + +
+ = + We assert + that no variable called + greeting + exist. Then we give the process a signal to move i= t to the auction state. We + want to associate the execution of the action with the event o= f 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. Bu= t moreover, the + greeting + variable should exist and contain the string "Hello from + ActionHandler". That's what we assert in the last l= ines of the test + method. + + = + + Running the tests now results in a failure. The point is th= at we did not associate + the action with any particular event in the process definition= , so the process variable + did not get set. + +
+ Test Results Before Integration + + + + + + +
+ + Let'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 act= ion 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 a= vailable under the action + icon in the right upper corner of the Properties View. + +
+ Adding an Action to a Transition + + + + + + +
+ + After adding the action a tabbed view with three pages will = appear. + +
+ Configuration Dialog for an Action + + + + + + +
+ + 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 i= s asynchronous. The + Details page is the most important. It allows to choose and co= nfigure the actual action + handler implementation. + +
+ The Details page of an Action Configuration Dialog</tit= le> + + <mediaobject> + <imageobject> + <imagedata fileref=3D"images/The_JBoss_jBPM_Int_Mech/j= boss_jbpm_int_mech_7.png" scale=3D"80"></imagedata> + </imageobject> + </mediaobject> + </figure> + + + <para>Clicking on the <emphasis> + <property moreinfo=3D"none">Search...</property> + </emphasis> button brings us to a Choose Class dialog.</para> + + + <figure float=3D"0"> + <title>The Choose Action Handler Dialog + + + + + + +
+ + + We choose our previously created 'HelloActionHandler' class= and + push the OK button. Aft= er the selection of the action handler for + the action, we can run the test and observe it gives us a gree= n light. + +
+ Test Results + + + + + + +
+ + Tere we are. The above objective has been achieved. +
+ +
+ Integration Points + + The different integration points in a process definition ar= e thoroughly documented in + the JB= oss jBPM User Guide. 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 navi= gate to this view by + selecting the added Action in the outline view. + +
+ + + + = + + + + + jBPM + + + + + + + Quick Howto Guide + + This chapter contains additional information related to the JBoss + jBPM. + +
+ Change the Default Core jBPM Installation + + You can change the default jBPM= installation by means of the + Eclipse preference mechanism. Open the Preferences dialog by s= electing + Window > Preferences + and select the + JBoss jBPM > Runtime Locati= on + category. Using this page you can add multiple jBPM + installation locations and change the default one. The default= installation is used for + the classpath settings when creating a new Process Project. Ch= anging the preferences has + no influence on already created projects. Getting rid of a jBPM + installation that's being referenced by a project however will= cause the + classpath to contain errors. + + +
+ The jBPM Preferences Page + + + + + + +
+
+ +
+ Configuring Task Nodes + + Here, we'll examine how you can configure the Task nodes in = jBPM jPDL GPD. + + You can add Tasks to Task nodes and then configure them in = a similar manner as the + Action configuration mechanism. Let's consider the process def= inition similar + to the previous one that contains three nodes: Start state, Ta= sk node and End state. The + Properties view for sel= ected Task node includes several tabs. + +
+ The Properties View of the selected Task Node + + + + + +
+ + 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. + +
+ Adding a Task to the Task Node + + + + + +
+ + Every added Task has its own configuration possibilities. Yo= u can access them through + the Properties view as = well. + +
+ The Task properties + + + + + +
+ + The General page is a= place where you can specify the name of a + Task and its description. For instance, let it be + approve oder + with appropriate description that you can see in t= he figure below. + +
+ The Task General Page + + + + + +
+ + Now, look at Details page. 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 + Blocking + attribute indicates that the process will not be a= ble to continue if this + task is still unaccomplished. The + Generate Form... + button is for creating a simple task form that can= be rendered by the jBPM + console. + +
+ The Task Details Page + + + + + +
+ + For our example, we specify the due date as 2 business days,= choose the high priority + and also check the + Signalling + and + Notify + attributes. It means that the Task should be accom= plished in 2 business days + and the assignee will be notified by email when the task is as= signed. To specify how the + Task should be assigned switch on to the Assignment page. + +
+ The Task Assignment Page + + + + + +
+ + On the Reminder page = you can specify whether the assignee will be reminded of the task + that awaits him. + +
+ The Task Reminder Page + + + + + +
+ + In our case, the assignee will be reminded by email after tw= o business hours and + continue to get reminding every business hour after that. + In the next figure you can see our configuring generated int= o XML. +
+ The Task Reminder Page + + + + + +
+ We hope, our guide will help you to get started with the jPD= L process language and jBPM + workflow on the whole. Besides, for additional information you= are welcome on our forum. +
+ + + = + + --===============0563809164492497902==--