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 that 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 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/JBoss 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
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 Internet Explorer and go to the following URL: http://localhost:8080/jbpm . 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 “cookie monster” 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 “Create new web sale order”. 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 “cookie” as the item, “1” as the quantity, and leave the address blank). Select “Save and Close Task” 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 “ernie”. There was also a timer created at the same time the task was created for “ernie”. Go to the console, and you will see a reminder message on the screen for “ernie” (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 “ernie”. Let’s switch back to the web browser. To login as “ernie”, first click “Login as another user”, then select “ernie” and click “Login”. The home page will now show a task to evaluate a web order (Figure 7).
Figure 7. Task to evaluate a web order
Click “evaluate web order”. This will show the task page again (Figure 8). Now, “ernie” is evaluating the data entered earlier. The address is missing, so enter a comment of “need address” and select “more info needed”.
Figure 8. Task page for evaluate web order.
The web application will signal JBoss jBPM to move the process along the “more info needed” path. JBoss jBPM will calculate the next node in the process, which is the “fix web order data” node. The next web page is the home page, with a notification that there is a task for “cookie monster”, who originally entered the web order data. Select “Login as another user, and log in as “cookie monster”. The home page will show the “fix web order data” task (Figure 9).
Figure 9. Home page with “fix web order data” task.
Select “fix web order data”. The task page appears with the comment “need address”. Enter an address (this example will use “123 main st”) (Figure 10) and select “save and close task”.
Figure 10. Task page with “fix web order data” task.
The web application signals JBoss jBPM to move the process to the next state. JBoss jBPM calculates the next step to be the “evaluate web order” node and assigns a task to the user “ernie”. Select “Login as another user” and select the user “ernie”. The home page shows a task to “evaluate web order”. Select this task, and the task page shows the updated data (Figure 11). The data is good now, so remove the comment and select “ok”.
Figure 11. Task page with address filled in.
The web application signals JBoss jBPM to move the process forward down the “ok” 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 “wait for money” and assigns a task to the user “bert”. Select “login as another user”, then login as “bert”, and select the “wait for money” task. The task page appears with a new field for money (Figure 13). Enter the money (“23.00” used for this example) and select “save and close task”.
Figure 13. Task page for “wait for money”
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 braches 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 “cookie monster” (Note: make the item “candy” this time). The next task will be for “ernie”.
- Evaluate the web order as “ernie” and select “more info needed”. The next task will be for “cookie monster”.
- Fix the web order as “cookie monster” by adding the address. The next task will be for “ernie”.
Note: Stay logged in as “cookie monster” for this next part.
We now have a process that is waiting for “ernie” to evaluate. Lets assume that “ernie” is unavailable to perform his task. How do we get this process moving now? Let’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 “Process Definitions List” to see a list of all processes deployed to JBoss jBPM (Figure 17).
Figure 17. Process Definition List page.
Click on the “2” 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 “ernie” so it doesn’t have an end date. Click on the “2” 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 “ernie” is unavailable, we will move the process forward ourselves. Click on the “End Task” link next to the unfinished task for “ernie”. 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 “Select” link next to the “ok” 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 “bert” 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 “bert” to go in and finish. Another way of finding process instances is searching by process variable. Click on the “Monitoring” tab in the left hand menu, then click on “Search Process Instances” link. The Search Instances page will come up (Figure 24).
Figure 24. Search Instances page.
Enter “item” as the variable name, and “cookie” 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 “cookie”.
Create your own process
We have seen the process that comes with jBPM. Let’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’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… 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 src/process folder, we see simple.par. We will create a new process definition in this same folder. Right click on the src/process folder, and select new, other… The new wizard shows again. This time select process definition under the JBoss jBPM folder (Figure 33).
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 (StatersProcess?), 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 “tracking number”, 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: “tracking number” (this time only select the read option), and “received date” 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 “address” 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 “amount” 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 “user(grover)” 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 “user(ernie)” (Figure 50).
Figure 50. Sales swimlane defined.
Click add again, and define a swimlane for Accounting that will go to “user(bert)” (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. 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.
Now that the process is deployed, let’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 “cookie monster” 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: