%%( font-size: 130%;)
JBoss jBPM getting started guide
Welcome to the JBoss jBPM getting started guide. In this guide, you will:
Download and unzip the JBoss jBPM Starter Kit
Execute the JBoss jBPM engine
Interact with the Websale sample process
Manage a process that is being executed
Create your own process
Deploy your process to JBoss jBPM
Before we get started, a couple of notes about this guide:
For those who are not familiar with workflow or business process management, please start with this article on the state of workflow: http://www.jboss.com/products/jbpm/stateofworkflow
This guide is not intended to show all of the features of JBoss jBPM. The intention is to show how to use the basic functionality of JBoss jBPM. At the bottom of this guide is a list of resources that will assist you with further use of JBoss jBPM.
This guide focuses on the jPDL process language, and does not go into web service orchestration using BPEL. BPEL is supported by JBoss jBPM, and more information about using BPEL with JBoss jBPM can be found in the BPEL extension download: http://www.jboss.com/products/jbpm/downloads
This guide was created with JBoss jBPM 3.1 and JBoss IDE 1.5.1. This guide is expected to be forward compatible with future versions of jBPM (although the screenshots may vary slightly). If you find any errors in this document please correct the wiki page or email kevin.barfield@Jboss.com.
JBoss jBPM is platform independent, but this guide was developed using a windows platform. This guide should work equally well for Unix/Linux installations because JBoss jBPM is 100% Pure Java. Obviously, you may need to download the tarball instead of the zipfile and use forward slashes instead of backslashes, etc.
Download and unzip the JBoss jBPM starter Kit
The JBoss jBPM starter kit (known as "suite" as of jBPM 3.2 Beta) contains everything needed to execute JBoss jBPM with the exception of Java itself. The JBoss Application Server in the JBoss jBPM starters kit requires either JDK 1.4 or JDK 1.5. If you do not have one of these on the machine that JBoss jBPM will be running on, please download it here: http://java.sun.com/j2se/1.4.2/download.html
Once you have Java installed, you are ready to download the JBoss jBPM starters kit. The following link has the list of downloads for JBoss jBPM: http://www.jboss.com/products/jBPM/downloads. Please select the JBoss jBPM starters kit and select to download it to your machine. From here, you will need to unzip it to your machine (Note: If you do not have Zip, please go to this link to get it: http://sourceforge.net/projects/sevenzip/ ).
Once you have unzipped it, you should have a directory structure with the following folders:
Jbpm-starters-kit-3.1 jbpm - Contains the source code for the JBoss jBPM product jbpm-bpel - Contains information about the BPEL extension for JBoss jBPM jbpm-db - Contains sample configurations to connect JBoss jBPM to other databases jbpm-designer - Contains the Eclipse plugin for the JBoss jBPM Visual Process Designer jbpm-server - Contains the JBoss application server along with the JBoss jBPM engine and the sample process dsds
Execute the JBoss jBPM engine
Go to the jbpm-server directory and double click on the start.bat. A command window should come up with the jBPM console (Figure 1).
Figure 1: jBPM console
Now, bring up your favourite web-browser and go to the following URL: http://localhost:8080/jbpm (http://localhost:8080/jbpm-console for 3.2GA). You should get a log in page for the sample web application for JBoss jBPM (Figure 2).
Figure 2. Login page for the JBoss jBPM sample web application.
Interact with the websale sample process
The sample web application interacts with the sample websale process that is deployed to JBoss jBPM (Figure 3). We will now use the sample web application to execute the websale process. Keep in mind that your web application may look similar or provide an entirely different user interface from the one presented in this sample.
Figure 3. The sample websale process that is deployed to JBoss jBPM.
The first step is to log in. There is a list of several users, we will choose &147;cookie monster&148; to start. When you select login, you will go to the homepage for this user. There is a tasklist for this user (which is currently empty) and the ability to create a new websale process (Figure 4). Please note the create link also shows the process name (websale) and the process version (1).
Figure 4. Homepage with Tasklist and Start New Process Execution
Click &147;Create new web sale order&148;. The web application will call JBoss jBPM to create a new instance of the websale process. The web page now shows the Task page (Figure 5). This page shows where you are in the process (Red box on the process image) and has a form for you to fill out. The variables in the form (item, quantity, and address) will become process variables in the websale process.
Figure 5. The task page, with the current process step shown on the right.
Fill out the item and quantity (for our example, we will use &147;cookie&148; as the item, &147;1&148; as the quantity, and leave the address blank). Select &147;Save and Close Task&148; to complete this task. The web application will then signal JBoss jBPM to move the websale process forward with the process variables entered. JBoss jBPM calculates the next state of the process, and determines who gets the task at the next node in the process. The next page shown will be the Home page again (Figure 6).
Figure 6. Home page after the task has been saved.
Notice there is a message saying that the next task has been assigned to the user &147;ernie&148;. There was also a timer created at the same time the task was created for &147;ernie&148;. Go to the console, and you will see a reminder message on the screen for &147;ernie&148; (Figure 7). This timer could call a Java business class to send an email reminder perform some other business function.
Figure 7. JBoss jBPM console showing a task waiting for &147;ernie&148;.
Let&146;s switch back to the web browser. To login as &147;ernie&148;, first click &147;Login as another user&148;, then select &147;ernie&148; and click &147;Login&148;. The home page will now show a task to evaluate a web order (Figure 7).
Figure 7. Task to evaluate a web order
Click &147;evaluate web order&148;. This will show the task page again (Figure 8). Now, &147;ernie&148; is evaluating the data entered earlier. The address is missing, so enter a comment of &147;need address&148; and select &147;more info needed&148;.
Figure 8. Task page for evaluate web order.
The web application will signal JBoss jBPM to move the process along the &147;more info needed&148; path. JBoss jBPM will calculate the next node in the process, which is the &147;fix web order data&148; node. The next web page is the home page, with a notification that there is a task for &147;cookie monster&148;, who originally entered the web order data. Select &147;Login as another user, and log in as &147;cookie monster&148;. The home page will show the &147;fix web order data&148; task (Figure 9).
Figure 9. Home page with &147;fix web order data&148; task.
Select &147;fix web order data&148;. The task page appears with the comment &147;need address&148;. Enter an address (this example will use &147;123 main st&148;) (Figure 10) and select &147;save and close task&148;.
Figure 10. Task page with &147;fix web order data&148; task.
The web application signals JBoss jBPM to move the process to the next state. JBoss jBPM calculates the next step to be the &147;evaluate web order&148; node and assigns a task to the user &147;ernie&148;. Select &147;Login as another user&148; and select the user &147;ernie&148;. The home page shows a task to &147;evaluate web order&148;. Select this task, and the task page shows the updated data (Figure 11). The data is good now, so remove the comment and select &147;ok&148;.
Figure 11. Task page with address filled in.
The web application signals JBoss jBPM to move the process forward down the &147;ok&148; path. JBoss jBPM calculates the next step in the process, which is a fork. JBoss jBPM then goes down each branch of the fork. For the shipping branch of the fork, there is no web interaction, just a message on the console (Figure 12).
Figure 12. Ship message on JBoss jBPM console.
For the payment branch, JBoss jBPM calculates the next node is &147;wait for money&148; and assigns a task to the user &147;bert&148;. Select &147;login as another user&148;, then login as &147;bert&148;, and select the &147;wait for money&148; task. The task page appears with a new field for money (Figure 13). Enter the money (&147;23.00&148; used for this example) and select &147;save and close task&148;.
Figure 13. Task page for &147;wait for money&148;
The web application signals JBoss jBPM to calculate the next state of the process. JBoss jBPM determines that update books is the next node in the process. This node does not interact with the web application, it puts a message on the JBoss jBPM console (
Figure 14).
Figure 14. JBoss jBPM console shows update books message.
JBoss jBPM continues to calculate the next state. Both branches of the fork are completed at this point, so the next state is the end state. The home page of the web application states that the process is finished (Figure 15).
Figure 15. Home page showing the process has finished.
Manage a process that is being executed
So far, we have interacted with JBoss jBPM through the sample webapp to create a process instance, fill in process variables, and signal the process to move forward until it is finished. Now we will view a process in mid-execution and move it forward as an administrator.
First, we need a process instance that is in the middle of execution. So, we are going to repeat some of the steps above:
Create a new websale order as &147;cookie monster&148; (Note: make the item &147;candy&148; this time). The next task will be for &147;ernie&148;.
Evaluate the web order as &147;ernie&148; and select &147;more info needed&148;. The next task will be for &147;cookie monster&148;.
Fix the web order as &147;cookie monster&148; by adding the address. The next task will be for &147;ernie&148;.
Note: Stay logged in as &147;cookie monster&148; for this next part.
We now have a process that is waiting for &147;ernie&148; to evaluate. Lets assume that &147;ernie&148; is unavailable to perform his task. How do we get this process moving now? Let&146;s go to the Monitoring menu. Select Monitoring on the left hand navigation, and the monitoring search page shows up (Figure 16).
Figure 16. Monitoring search page.
From here we can search for all process instances, search for process instances by process variables, or go to a specific process instance by id. Click on &147;Process Definitions List&148; to see a list of all processes deployed to JBoss jBPM (Figure 17).
Figure 17. Process Definition List page.
Click on the &147;2&148; in the instances column to see the process instances for the websale process. The process instance list page comes up (Figure 18).
Figure 18. Process Instances List page.
Here we see the two processes that we created. The first one has an end date because it finished processing. The second one is waiting for &147;ernie&148; so it doesn&146;t have an end date. Click on the &147;2&148; in the Id column to see the process instance detail page (Figures 19 and 20).
Figure 19. Process Instance detail page (top).
Figure 20. Process Instance detail page (bottom).
On this page we can see:
The tasks that have been created as part of this process instance
The process variables associated with this process instance
The tokens for this process instance that represent where in the process the execution currently is
A graphical view of the process and which node the process is currently at.
Since &147;ernie&148; is unavailable, we will move the process forward ourselves. Click on the &147;End Task&148; link next to the unfinished task for &147;ernie&148;. There are multiple transitions from this node, so the available transitions page will come up (Figure 21).
Figure 21. Available transitions page.
Since the order data is correct, click on the &147;Select&148; link next to the &147;ok&148; transition. The process instance detail page will come back up (Figures 22 and 23).
Figure 22. Process Instance detail page (top).
Figure 23. Process Instance detail page (bottom)
Notice that there is a new task for &147;bert&148; now, and there are two new tokens representing each branch of the fork. The diagram is also updated to show the two new tokens. The process is now ready for &147;bert&148; to go in and finish.
Another way of finding process instances is searching by process variable. Click on the &147;Monitoring&148; tab in the left hand menu, then click on &147;Search Process Instances&148; link. The Search Instances page will come up (Figure 24).
Figure 24. Search Instances page.
Enter &147;item&148; as the variable name, and &147;cookie&148; as the variable value. The process instance detail page will then display the one process instance that match this criteria (Figure 25). If there were multiple process instances that matched the criteria, then the process instance list page would show all of those process instances.
Figure 25. Process Instance detail page for process with item &147;cookie&148;.
Create your own process
We have seen the process that comes with jBPM. Let&146;s now create a new process. Since the existing process is a web order process, lets create a process for returns of orders. This process will start with the buyer returning the item, then shipping receives the order. After that, the original order can be updated, and the money refunded. The process will then be complete.
There are three ways to create a process with JBoss jBPM:
Draw the process with the visual process designer
Write the process in XML format
Dynamically create the process through Java business logic
For this guide, we will be using the visual process designer. The visual process designer is part of the JBoss IDE plugins to the Eclipse platform. This guide assumes that Eclipse is not currently on the workstation, and so we will download the bundled version of Eclipse with the JBoss IDE plugins. Go to the JBoss IDE download page (http://www.jboss.com/products/jbosside/downloads), select the most recent GA version, and then select the bundled version of the zip. Unzip this download to your hard drive. There should be an eclipse directory where this was installed, with an eclipse.exe in it.
Use this to start eclipse. A dialog box will come up asking where to setup the workspace (Figure 26).
Figure 26. Workspace Selection dialog.
This is where the project you create will be stored on the hard drive. Choose your workspace location, and select Ok. The next dialog will be the JBoss IDE welcome dialog (Figure 27).
Figure 27. JBoss IDE Welcome Dialog
We don&146;t need to convert an existing project, so select Cancel. The main eclipse welcome page is shown (Figure 28).
Figure 28. Eclipse welcome page
Select the arrow icon in the upper right for the workbench. This will take us to the workbench view (Figure 29).
Figure 29. Eclipse workbench view.
From here, we will create a process project and a process definition. First, select File, new, other&133; This will show a dialog with a list of projects to create (Figure 30).
Figure 30. New project wizard selection page.
Select Process Project under the JBoss jBPM folder and click Next. The new process project dialog is shown (Figure 31).
Figure 31. New Process Project dialog.
Enter the project name, and select Finish. The workbench view is shown again, now with the jBPMStartersProcess project in the left hand window (Figure 32).
Figure 32. Workbench with jBPMStarters process.
There is a process already defined in this project. Under the processes/simple folder, we see processdefinition.xml. We will create a new process definition in this same folder. Right click on the processes/simple folder, and select new, other&133; The new wizard shows again. This time select process definition under the JBoss jBPM folder (Figure 33). (Note: that the project layout is subject to change, and that the screenshots may not be consistent with these textual instructions).
Figure 33. New project wizard dialog with Process Definition selected.
Select Next, and the new process definition dialog shows (Figure 34).
Figure 34. New process definition dialog.
Enter the name of the process (StartersProcess), and select Finish. The workbench shows again with the new process in the left hand navigation. In addition, the visual process designer now shows as well (Figure 35).
Figure 35. Workbench with visual process designer.
Now that we have created a blank process, we can draw the process out. This process will have:
a start state
a task node
a fork
two more task nodes
a join
an end state
Please see Figure 36 as to how these are laid out.
Figure 36. Node layout for the new process.
Note that as you added the nodes, they automatically showed up in the outline on the right hand window. Now that we have nodes, we can add transitions. Click on the transition button, and draw transitions between the nodes. See Figure 37 for how this should look.
Figure 37. StartersProcess with transitions.
Note that the transitions also show up in the outline on the right hand window as well. From here, we will rename some of the nodes and transitions to make the process more readable. To do this, click on the node and the name will become enterable, or double click and use the dialog to enter the new name. See Figure 38 for the process with the names filled in.
Figure 38. StartersProcess with the nodes and transitions renamed.
The StartersProcess has nodes and transitions, so lets add tasks next. Right click on the Ship Order Return node, and select add task. A task will show in the right hand window under that node (Figure 39).
Figure 39. Starters Process with a task added.
To customize this task, right click on the task and select properties. The properties dialog shows up (Figure 40).
Figure 40. Task general properties dialog.
The general properties dialog has the name for the task. Enter Send Item as the task name. Click on Controller to add a process variable to this task (Figure 41).
Figure 41. Task controller dialog.
Click Add to add a process variable. Change the name to &147;tracking number&148;, and select the read, write and required flags (Figure 42).
Figure 42. Task Controller dialog filled in.
Click OK to finish defining this task. We will now repeat the process to create the other tasks in the process, and assign process variables to each. Right click on the Receive Return node, and add a task. Right click on the task and select properties. Change the name of the task to Receive Item, and add two process variables: &147;tracking number&148; (this time only select the read option), and &147;received date&148; with read, write and required selected (Figure 43).
Figure 43. Controller dialog for the Receive Return task.
Click OK to finish defining this task. Right click on the Update Order node, and add a task. Right click on the task and select properties. Change the name of the task to Send Updated Order, and add the process variable &147;address&148; with read, write and required selected (Figure 44).
Figure 44. Controller dialog for the Send Updated Order task.
Click OK to finish defining this task. Right click on the Return Money node, and add a task. Right click on the task and select properties. Change the name of the task to Update Books, and add the process variable &147;amount&148; with read, write and required selected (Figure 45).
Figure 45. Controller dialog for the Update Books task.
Click OK to complete the task. The outline on the right hand side now shows all four tasks (Figure 46).
Figure 46. StartersProcess with tasks defined.
The tasks have been defined, but we still need to define who should do each task. We will do this by first creating swimlanes, then assigning tasks to the swimlanes. Click on Swimlanes at the bottom of the process diagram to view the swimlanes page (Figure 47).
Figure 47. Swimlanes dialog.
Click Add to create an empty swimlane (Figure 48).
Figure 48. Empty swimlane created.
Enter the name of the swimlane as Shipping, and make the assignment type expression. A box appears for the expression. We will do a very simple assignment to a user that has already been setup. Enter &147;user(grover)&148; to assign this swimlane to grover (Figure 49).
Figure 49. Shipping swimlane defined.
Click add again, and define a swimlane for Sales that will go to &147;user(ernie)&148; (Figure 50).
Figure 50. Sales swimlane defined.
Click add again, and define a swimlane for Accounting that will go to &147;user(bert)&148; (Figure 51).
Figure 51. Accounting swimlane defined.
Now that the swimlanes are defined, tasks can be assigned to the swimlanes. Right click on the Receive Item task and select properties. Select the Assignment link on the left hand side to show the assignment dialog. Select Swimlane as the assignment type, and then choose the Shipping swimlane (Figure 52).
Figure 52. Shipping swimlane chosen for task Receive Item.
Click OK. Right click on the Send Updated Order task and select properties. Select the Assignment link on the left hand side to show the assignment dialog. Select Swimlane as the assignment type, and then choose the Sales swimlane (Figure 53).
Figure 53. Sales swimlane chosen for task Send Updated Order.
Click OK. Right click on the Update Books task and select properties. Select the Assignment link on the left hand side to show the assignment dialog. Select Swimlane as the assignment type, and then choose the Accounting swimlane (Figure 54).
Figure 54. Accounting swimlane chosen for task Update Books.
Click OK. We have now defined the process by adding nodes and transitions, then adding tasks and swimlanes. Click save to save the process definition. We are now ready to deploy the process definition to JBoss jBPM.
Deploy your process to JBoss jBPM
Right click on the StartersProcess.par folder in the left hand project window, and select Deploy Process Archive option. The Process Deployment dialog is displayed (Figure 55).
Figure 55. Process Deployment Dialog.
Note: JBoss jBPM needs to be running for process definitions to be deployed through this tool.
If JBoss jBPM is running on the same machine as the Eclipse plugin, then leave the options as the default (starting 3.2GA you have to change the deployer field to jbpm-console/upload). If JBoss jBPM is running on a different machine, enter the server name for the server it is running on. Click Finish to deploy the process. The Success message should appear (Figure 56).
Figure 56. Deployment Successful dialog.
For JBossIDE-1.6.0.GA deployment is different:
While you have your process open, click on the "Deployment" tab down in the bottom/middle of the screen. It will bring you to the picture shown above. Make sure your xml files(and if any other files are needed) are checked (as shown in the image above). In the deployment server settings put the server name (where the jBPM server is located, not your database server) and the server port (again for the jBPM server), then hit "deploy process archive..", it will give you a confirmation screen.
If you are having problems deploying make sure to check for syntax errors in your XML, and also you may want to try hitting the "test connection" button to see if you can even reach the server, (plus it gives you an error message that usually is detailed enough to figure it out).
Now that the process is deployed, let&146;s use the sample web application to run through the process. Bring up Internet Explorer and go to the following URL: http://localhost:8080/jbpm . Log in as &147;cookie monster&148; and there are now two options under Create New Process Execution (Figure 57).
Figure 57. Home page showing StartersProcess task.
Click the Send Item task. The process definition we created now shows on the page, along with the process variable we created (Figure 58).
Figure 58. Task page for StartersProcess showing the tracking number process variable.
From here, you can run through the rest of the process execution.
Congratulations! In this guide, you have:
Downloaded and unzipped the JBoss jBPM Starter Kit
Executed the JBoss jBPM engine
Interacted with the Websale sample process
Managed a process that is being executed
Created your own process
Deployed your process to JBoss jBPM
Here are some further resources to use when exploring JBoss jBPM:
JBoss jBPM User Guide 3.1 http://docs.jboss.com/jbpm/v3/userguide/
JBoss jBPM Javadoc 3.1 http://docs.jboss.com/jbpm/v3/javadoc/
JBoss jBPM Process Designer Getting Started 3.0 http://docs.jboss.com/jbpm/v3/gpd/
JBoss jBPM Training http://www.jboss.com/services/training/jbpm
JBoss jBPM Book (Upcoming)
Appendix: FAQ
Question: Why does the run.bat not work when I try it from the starters kit?
Answer: The JBoss jBPM starters kit contains the JBoss Application Server. This JBoss Application Server is already configured to use jBPM. The JBoss jBPM configuration is in a directory called &145;jbpm&146;. There is a start.bat file in the following directory that tells the run.bat to use the jbpm configuration.
jbpm-starters-kit-3.1>jbpm-server
If you would like to use run.bat to start the JBoss Application Server with the JBoss jBPM starters kit, please use the following parameter: run.bat &150;c jbpm
Question: Where is the source code for the web application located?
Answer: When you download the jBPM starters kit, there is a jbpm directory. This includes the source for jBPM itself, the sample web app, and the websale process.
The sample web app bean source code is located in:
jbpm-starters-kit-3.1>jbpm>src>java.webapp
The sample web app front end (jsp) source code is located in:
jbpm-starters-kit-3.1>jbpm>src>resources>jbpm.war
The websale process definition is located in:
jbpm-starters-kit-3.1>jbpm>src>process.examples
Question: Where does the process definition go when it is deployed to JBoss jBPM?
Answer: The process definition is stored in the database that is used by JBoss jBPM. This allows JBoss jBPM to version process definitions.
Question: Can I modify the JBoss jBPM web application?
Question: Do I have to use the JBoss jBPM web application, or can I create my own?
Answer: The web application shown in this getting started guide is intended to allow you to develop and deploy processes quickly, and to give a code example of how an application would interact with the JBoss jBPM engine. Please be aware that the web application is licensed under the LGPL if you plan to modify the web application code and re-distribute it as part of a product. You can create your own front end application that interacts with the JBoss jBPM engine, or use JBoss jBPM without a front end application at all for processes that don&146;t require a front end interface.
Question: How do I add a user to JBoss jBPM?
Answer: JBoss jBPM has an identity module that has the concepts of users, groups, and memberships. This information is stored in the database that JBoss jBPM uses by default, but you can change it to use LDAP or a 3rd party identity solution. This link has more information about the identity component in jBPM: http://docs.jboss.com/jbpm/v3/userguide/taskmanagement.html#theidentitycomponent
Here is a link to the JBoss jBPM Data Model: http://wiki.jboss.org/wiki/Wiki.jsp?page=Jbpm31DataModel
Now, let&146;s add a user to JBoss jBPM using our starters kit example. The JBoss jBPM starters kit example does not provide a page for adding users, so we will manually add the user to the JBoss jBPM database. We will do this by adding a user to the jbpm_id_user table, and the web application will read users from that table. First, we need to access the database (Note: JBoss jBPM needs to be running before you do this). We will do this through the jmx console that comes with the JBoss Application Server. Internet Explorer and go to the following URL: http://localhost:8080/jmx-console. The JMX console will appear (Figure 59).
Figure 59. JMX Console for the JBoss Application Server.
From here, click on the Hypersonic database entry to get details (Figures 60 and 61).
Figure 60. JMX view for the Hypersonic database
Figure 61. Start Database Manager operation (further down on the same page).
Click on the &145;Invoke&146; button below the startDatabaseManager operation. The success page should show (Figure 62), and the database manager should appear (Figure 63).
Figure 62. Success page for starting the database manager.
Figure 63. HSQL Database Manager.
We will now write the SQL to add a row to the jbpm_id_user table. This table has the following fields:
id_
class_
name_
email_
password_
For this example, we will insert a user with id &145;5&146;, class &145;U&146;, name &145;Bill Buyer&146;, email &145;bill@jbpm.org&146;, and password of &145;mypassword&146;. The SQL to do this is below:
insert into jbpm_id_user values (5, 'U', 'Bill Buyer', 'bill@jbpm.org', 'mypassword');
Put this into the text box and click &145;Execute SQL&146;. The lower box should show that one record was inserted (Figure 64).
Figure 64. Row successfully inserted into the jbpm_id_user table.
Note: You will need to change the id for each user you add, or you will get an SQL error.
Finally, go back to the web application for JBoss jBPM and click on the user dropdown. Bill Buyer now shows up as a user (Figure 65).
Figure 65. Bill Buyer now appears in the user list.
%%
Comments