Working with the BPM Suite Example App

Red Hat JBoss BPM Suite 6.0

Get started with the BigApp (BPM Suite Example App)

Vikram Goyal

Eva Kopalova

Red Hat Content Services


The guide to help you install and navigate the BPM Suite Example App (BigApp)

Chapter 1. Introduction

1.1. About Red Hat JBoss BPM Suite

Red Hat JBoss BPM Suite is an open source business process management suite that combines Business Process Management and Business Rules Management and enables business and IT users to create, manage, validate, and deploy Business Processes and Rules.
Red Hat JBoss BRMS and Red Hat JBoss BPM Suite use a centralized repository where all resources are stored. This ensures consistency, transparency, and the ability to audit across the business. Business users can modify business logic and business processes without requiring assistance from IT personnel.
To accommodate Business Rules component, Red Hat JBoss BPM Suite includes integrated Red Hat JBoss BRMS.
Business Resource Planner is included as a technical preview with this release.

1.2. Red Hat JBoss BPM Suite components

The Red Hat JBoss BPM Suite contains the following components:
Execution Engine
The runtime environment for business assets (Processes, Tasks, Rules, etc.). For further details, refer to the Red Hat JBoss BPM Suite Administration and Configuration Guide.
Artifact Repository (Knowledge Store)
A storage for business assets that provide revision control capabilities (connects GIT repositories with business assets).
Business Central
A web-based application for asset creation, management, and monitoring of business assets providing an integrated environment with the respective tools, such as, rule and process authoring tools, business asset management tool for work with Artifact Repository, runtime data management tools, resource editors, BAM (Business Activity Monitoring) tools, Task management tools, and BRMS tools. For further details, refer to the Red Hat JBoss BPM Suite User Guide.

1.3. Use Case: Process­-based solutions in the loan industry

Red Hat JBoss BPM Suite (BPMS) can be deployed to automate business processes, such as automating the loan approval process at a retail bank. This is a typical 'Specific Process-Based' deployment that might be the first step in a wider adoption of BPM throughout an enterprise. It leverages both the BPM and business rules features of BPMS.
A retail bank offers several types of loan products each with varying terms and eligibility requirements. Customers requiring a loan must file a loan application with the bank, which then processes the application in several steps, verifying eligibility, determining terms, checking for fraudulent activity, and determining the most appropriate loan product. Once approved, the bank creates and funds a loan account for the applicant, who can then access funds. The bank must be sure to comply with all relevant banking regulations at each step of the process, and needs to manage its loan portfolio to maximize profitability. Policies are in place to aid in decision making at each step, and those policies are actively managed to optimize outcomes for the bank.
Business analysts at the bank model the loan application processes using the BPMN2 authoring tools (Process Designer) in BPM Suite:
High-level loan application process flow

Figure 1.1. High-level loan application process flow

Business rules are developed with the rule authoring tools in BPM Suite to enforce policies and make decisions. Rules are linked with the process models to enforce the correct policies at each process step.
The bank's IT organization deploys the BPM Suite so that the entire loan application process can be automated.
Loan Application Process Automation

Figure 1.2. Loan Application Process Automation

The entire loan process and rules can be modified at any time by the bank's business analysts. The bank is able to maintain constant compliance with changing regulations, and is able to quickly introduce new loan products and improve loan policies in order to compete effectively and drive profitability.

Chapter 2. BPM Suite Example App

2.1. Introducing the BPM Suite Example App

The BPM Suite Example App is a functional Red Hat JBoss BPM Suite demo app that mimics the functionality of the rules and processes followed in approving or rejecting the application for a mortgage to buy a property. It showcases the rules, web services and human tasks involved in evaluating a mortgage application.
This example app is provided as a deployable GIT repository that can be cloned locally and installed to a local instance of BPM Suite running on Red Hat JBoss Enterprise Application Platform.


The BPM Suite Example App runs in-memory and there is no persistence involved. Anything that you create using this App is not saved. This means that if you need to restart the underlying server, you will lose your process instances, data and monitoring history.
The app introduces you to and showcases the following functionality in Red Hat JBoss BPM Suite:
  • Advanced processes
  • Human Tasks assigned to multiple roles
  • Use of Swimlanes
  • Guided business rules
  • Technical rules
  • Guided web decision tables
  • Script Tasks for Java work
  • Web Service tasks using SOAP/HTTP
  • Use of the BPMS Data Modeler for creating the Java fact model
  • Use of graphic form designer to create forms with examples of Javascript validation
  • Helper jar to pre-load process instances in various states
The following figure represents the process flow within the BigApp.
BigApp Mortgage Approval Process Flow

Figure 2.1. BigApp Mortgage Approval Process Flow

Chapter 3. BPM Suite Example Setup

3.1. Downloading the BPM Suite Example App

To download the BPM Suite Example App, do the following:
  1. Go to the Red Hat Customer Portal and log in.
  2. Select DownloadsProduct Downloads.
  3. In the Product Downloads page that opens, click Red Hat JBoss BPM Suite.
  4. From the Version drop-down menu, select the product version 6.0.3.
  5. Select Red Hat JBoss BPM Suite 6.0.3 Quick Starts and then click Download.

3.2. Creating users and roles

  1. Using the terminal, navigate to the jboss-eap-6.1/bin directory.
  2. To add application users, run the command on a Unix system, or add-user.bat on a Windows system from the bin directory.
  3. Enter b at the type of user prompt and press Enter.
  4. Accept the default Realm (ApplicationRealm): by pressing Enter.
  5. At the username prompt, enter the user name hank and confirm.
  6. Create the user's password at the password prompt and reenter the password.
  7. Enter the roles admin,appraiser,broker,manager separated by commas at the roles prompt and confirm.
  8. Confirm you want to add the user.
  9. Enter no at the last prompt.


Usernames, passwords, and roles are case sensitive.

3.3. Starting the server


It is assumed that you have a functional Red Hat JBoss BPM Suite already downloaded and installed. If not, please refer to the Red Hat JBoss BPM Suite 6 Installation Guide.
  • Start the Red Hat JBoss BPM Suite server (if not already started):
    1. On the command line, move into the $SERVER_HOME/bin/ directory.
    2. In a Unix environment run:
      In a Windows environment run:

3.4. Logging in to Business Central

Logging in to Business Central

Figure 3.1. Logging in to Business Central

3.5. Installing the BPM Suite Example App

Now that you have downloaded the BPM Suite Quick Starts, it is time to install the BPM Suite Example App on a running Red Hat JBoss BPM Suite.
  1. Open Business Central in your web browser (if running locally, http://localhost:8080/business-central) and log in as a user with the admin role.
  2. Create a Demo organizational unit:
    1. Go to AuthoringAdministration.
    2. On the perspective menu, select Organizational UnitsManage Organizational Units.
    3. In the displayed Organizational Unit Manager view, click Add.
    4. In the displayed Add New Organizational Unit dialog box, define the unit properties and click OK:
      • Name: Demo
      • Owner:
  3. Extract the zip package you downloaded from Red Hat Customer Portal on a local folder on the server. This unzipped version of the zip file contains the folder jboss-bpm-example which contains the GIT repository in the mortgage-demo folder and this is what we will now import.
  4. In Business Central, go to AuthoringAdministration.
  5. On the perspective menu, click RepositoriesClone repository.
  6. In the displayed Clone Repository dialog box, define the repository properties:
    • Repository Name: Mortgages
    • Organizational Unit: Demo
    • Git URL: file:///${PATH-TO-UNZIPPED-FOLDER}/mortgage-demo/.git


    Make sure to replace ${PATH-TO-UNZIPPED-FOLDER} with the actual location. Also note that after the file: protocol, there are three forward slashes ///.
    Leave the items Username and Password empty.
    The repository is now cloned and the Mortgage repository is visible in File Explorer. You now need to build and deploy this project.
  7. Go to AuthoringProject Authoring.
  8. In Project Explorer, select DemoMortgages.
  9. Select ToolsProject Editor and on the panel that opens, click the Build & Deploy button. Confirm the changes and add a check in comment if required. A green bar at the top will let you know if the project builds successfully.
  10. You now need to deploy the Mortgage Demo Web Service on the BPM Suite server. To do this, locate the web application archive file jboss-mortgage-demo-ws.war in the unzipped local folder and copy it to ${BPM Server Dir}/standalone/deployments/.
  11. Now we will load the Mortgage Demo project with a few process instances in various stages of workflow. These instances are provided in a file called jboss-mortgage-demo-client.jar. These instances help you to play with the Mortgage Demo without needing to create them yourself. You can safely skip this step if you would much rather create these instances yourself.


    A known bug (1033590) causes the installation of these client processes to fail when being run on some older Java Development Kits (JDK). Specifically, JDK versions less than 1.7.0_17 are known to be vulnerable. Please make sure to run the following commands on environments that are at least 1.7.0_17 or more recent.
    In a new terminal emulator window, navigate to the location where you unzipped the BPM Suite Example App file (jboss-bpm-example-dist-1.MINOR_VERSION-redhat-x), and run the following command
    java -jar jboss-mortgage-demo-client.jar USERNAME PASSWORD http://localhost:8080/business-central com.redhat.bpms.examples:mortgage:1
    For example:
    java -jar jboss-mortgage-demo-client.jar admin your_password http://localhost:8080/business-central com.redhat.bpms.examples:mortgage:1


    Make sure to replace the username and password with your own username and password. This username must have admin access within the BPM Suite Server.


    Make sure that your Red Hat JBoss BPM Suite server is running when you run the above command.
    A successful execution will load these processes in your BPM Suite Server. Check the server log to see the application log outputs for confirmation.

Chapter 4. BPM Suite Example App Process Flow

4.1. BPM Suite Example App Mortgage Approval Process Flow

4.1.1. Input Data

The mortgage application begins at the start node by using a graphical form designed with the graphical form designer of BPM Suite to input data from the applicant, which include the applicant's personal information, annual income, social security number, the address and price of the property, and the down payment.

4.1.2. Validation

Once the beans are created, the next step is a business rule task, which does validation on the beans. It uses five business rules that have been created using the guided rule editor to validate information such as the format of the social security number, the down payment, or the amortization.

4.1.3. Data Correction

If anything is found to be invalid, a human task is used for data correction. The broker gets in touch with the applicant and attempts to correct the data. There is a swim lane for the broker, so the same broker that was assigned to correct the data the first time does it again if necessary, or any other task required by a broker is always done by the same broker for this particular mortgage application. After the correction, validation is reset and performed again. Once the data is valid, the process continues to the credit report.

4.1.4. Credit Report

The credit report is obtained via a web service task that calls a web service using SOAP over HTTP that has been created as part of the BPM Example App and deployed on the underlying platform. Based on the social security number sent, this task returns a credit score for the applicant.

4.1.5. Mortgage Calculations

The credit score is then used in the next step for mortgage calculation, which is again a business rule task. The business rule task is tied to a couple of different business rules and a guided web decision table. The decision table looks at the bracket for the credit score of the applicant as well as amortization and produces an interest rate. Other rules include figuring out the ratio of the down payment to the sales price and whether this is a jumbo loan, in which case there is a premium. All of the values result in the interest rate. The interest rate is used in the next node, again a script task, where Java code does a simple calculation based on the interest rate, the sale price minus the down payment, and the amortization calculates the monthly mortgage payments.

4.1.6. Qualify Borrower script task

The monthly mortgage payments are compared to the annual income of the applicant, and if the ratio is too high, the mortgage is not qualified and is denied. If the ratio is OK, it is qualified.

4.1.7. Appraisal

If the mortgage is qualified, the only remaining step is the appraisal on the property.
It is done using an appraiser human task, where an appraiser claims the task, looks at the property, and based on the address and the sales price determines an appraised value. The appraised value is compared with the sales price of the property.
If it is the same or higher, the mortgage is approved. If the appraised value is lower than the property's sale price, it affects the mortgage and the ratio of the down payment.
In that case, we go back to the cycle of calculating the interest rate again, this time based on the appraised value, as opposed to the property sale price, to see whether the borrower is qualified. If they are, this process concludes and the mortgage is approved. If they are not, they are prompted by their broker to increase the down payment. As long as they are able to increase the down payment, we can make another attempt to do the calculation, but if they do not qualify and they can no longer increase the down payment, we go to a financial review, which is done by a manager.
The financial review is the last resort, where the manager looks at the mortgage application and has the chance to override the decision and approve the mortgage. If they do approve the mortgage, it is approved and the process ends. If they deny it, it is denied and the process ends as well.

4.2. Navigating through the major parts of the BPM Suite Example App

4.2.1. Process Management

  1. To start the mortgage application process, go to Process Management Process Definitions on the main menu. The process definition is displayed on the list. If you cannot see the process definition, click Refresh.
  2. Start the process by clicking the Start button next to the Process definition entry. The Form dialog box is displayed.
  3. Fill out your name, address, and the rest of the details.
  4. Click the play button to instantiate the process.


There are some basic rules that you need to follow to make sure the process input data is accepted without the need to use a Data Correction task:
* Social security number (SSN) is validated by the Validate SSN rule in the Validation task. The validation rule accepts any 9-digit number as a valid SSN.
* The Validate Amortization rule determines that for amortization, you can enter a value of 10, 15, or 30 only. The rule is defined in the BPM Suite Example App. If you enter a different amortization value, the BPM Suite Example App creates a Data Correction human task, where you have to change the value.
If any of the entered data is not valid, it fails validation and the business rule that applied to the scenario is displayed in the log. In that case, a human task is used for data correction. For this we need a broker. The user we have in the BPM Example App has the various roles of a broker, an appraiser, and a manager, so all actions can be performed without having to log out and back in, which might not be the case in a real application.

4.2.2. Data Correction Task

In case the entered data is not valid and validation fails, a data correction task is available to claim and work on.
  1. To claim a data correction task, click the claim button to confirm you are going to work on the task.
  2. To complete the task, click the complete button and correct the data in the displayed Data Correction form.
  3. When the data is fixed, click the complete button at the bottom of the form. A yellow notification appears in the upper part of the screen informing you that the form was completed.
If you click the drop down arrow in the upper right hand corner of the Business Process tab and select the Guided Editor in the displayed drop down menu, the rule that applied, the cause, and standard output will be displayed.
If you select the Decision Table from the drop down menu and view its content, you can see the credit score returned by the web service, the APR, or the monthly payment.

4.2.3. Doing Appraisal

In the BPM Suite Example App, the created user also has the role of an appraiser, and therefore is able to work on the appraisal.
To work on the appraisal, do the following:
  1. On the tasks list, claim the appraisal task by clicking the Lock button. A yellow notification appears in the upper part of the screen informing you that the task is successfully claimed.
  2. To complete the task, click the Complete button and fill out the data in the displayed form.
If the appraisal is low, the calculation is performed again, and if not qualified, the borrower gets a chance to increase the down payment. There is a task for increasing the down payment that is automatically assigned to the same person who previously worked on the mortgage application.
To work on the task for increasing the down payment, do the following:
  1. Click the Start button to start working on the task.
  2. Use the button to complete it. The displayed form contains the data including the down payment, which is the only value that can be changed.
If the task is completed without increasing the down payment, the application process continues to a financial review done by a manager.

4.2.4. Mortgage Approval

In the BPM Suite Example App, the same user is able to claim the task as a manager by clicking the ( ) button and the ( ) button to start working on it.
The displayed form contains a review of all relevant data.
To approve the mortgage, check the box Approve Mortgage on the left hand side at the bottom of the form and click the ( ) button to complete the task.
By approving the mortgage, the business process is successfully finished.

Chapter 5. Example Process Instances

The BPM Example App provides you with several process instances in various stages of the Example App workflow. This can help you to play around with the app without needing to create a process instance from scratch.
These instances are added via an executable JAR file and you may have already installed them on your BPM Suite server in the last step of section Section 3.5, “Installing the BPM Suite Example App”. If not, please install these instances now.
  • User qualifies with a very low interest rate, great credit, non-jumbo loan: Amy
  • User qualifies with very low interest rate, great credit, non-jumbo loan: Andy
  • User qualifies with low interest rate, good credit, non-jumbo loan: John
  • User qualifies with low interest rate, good credit, non-jumbo loan: Jane
  • User qualifies with lower interest rate, great credit, jumbo loan: Liz
  • User qualifies with lower interest rate, great credit, jumbo loan: Larry
  • User qualifies with a bit higher interest rate, good credit, jumbo loan: Max
  • User qualifies with a bit higher interest rate, good credit, jumbo loan: Marry
  • User DOES NOT qualify with interest rate too high, terrible credit and jumbo loan: Joe
  • User DOES NOT qualify with down payment too low and jumbo loan: Jill
  • User DOES NOT qualify with down payment too low and jumbo loan: Rachel
  • User DOES NOT qualify with down payment too low and jumbo loan: Raphael
  • User provided incorrect SSN: Jennifer
  • User provided incorrect SSN: Jason
  • User with amortization not offered: Mike
  • User with amortization not offered: Molly

Appendix A. Revision History

Revision History
Revision 1.0.0-9.29Mon Oct 20 2014Rüdiger Landmann
Add new metadata BZ#1130629
Revision 1.0.0-9Mon Sep 22 2014Vikram Goyal
Built from Content Specification: 22691, Revision: 711717 by vigoyal

Legal Notice

Copyright © 2014 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.