Loan Application Form

Building a JBoss BPMS Web Application using jBPM Form API

(This article assumes some basic knowledge of the JBoss BPM Suite including using Business Central.)

JBoss BPMS forms are generated and customised by business analysts when they create business processes. The forms are usually used for kicking off a business process instance and interacting with the user when the process reaches a user task eg, for a manager to manually approve a loan. Few customers use the forms on the BPMS Execution Servers. They prefer to build a web application that interacts with a business process remotely running on a BPMS Execution Server to gain fine-grained access control, consistent look-and-feel and better client interaction. The main issue is how to use the forms generated on the BPMS server from the web application. There was no easy way to do that until the recent release of JBoss BPMS 6.1.

In a previous article, I outlined an approach in which the BPMS form metadata is run through a code generator to output JSPs for the UI and Java classes to handle these JSPs (ie, automating the creation of forms for process instantiation and manual task interaction). The Java classes constitute the Model part in the MVC (Model-View-Controller) design pattern. JBoss BPMS 6.1 includes a new API called jBPM Form API. The surprising thing about it is that it is not mentioned in the release notes nor is it described anywhere in the product documentation. In this article, I am going to show you how you can use this new API from a web application to interact with forms on the BPMS server. This JavaScript API provides a simple mechanism to use forms on remote applications by allowing loading of forms from different KIE Workbench instances, submit them, launch processes, tasks and execute callback functions when the actions are done.


This demo application uses the Stripes MVC framework (described in the aforementioned article) to form the main skeleton of the web application. The objectives of this demo application include:

  • demonstrating how a web application can interact with BPMS forms from a web application using the new jBPM Form API instead of the BPMS REST-based Remote Java API which is used in the previous article
  • illustrating how these two approaches differ in the interaction with BPMS and their implications

The jBPM Form API

The jBPM Form API is contained in the file in the BPMS install Directory: /pathToBPMSInstallDirectory/jboss-eap-6.4/standalone/deployments/business-central.war/js/jbpm-forms-rest-integration.js. Copy it to your web application. The JQuery AJAX library is also required.

The API consists of the following methods:

  • showStartProcessForm
  • showTaskForm
  • startProcess
  • claimTask
  • startTask
  • releaseTask
  • saveTask
  • completeTask

The way the API starts a Mortgage business process instance is depicted in the following UML sequence diagram.

Application and Form API Interaction
Application and Form API Interaction

The request/response using the showTaskForm call is shown below:










The API then uses the returned url as the “src” in an <iframe> element for rendering inside a <div> element, a container unit that encapsulates other page elements and divides the HTML document into sections.

<iframe id='formcontainer_form' src='http://localhost:8080/business-central/kie-wb.html?perspective=FormDisplayPerspective&standalone=true&opener=localhost:8080&taskId=1' frameborder='0' style='width:100%; height:100%'></iframe>

The forms you see from your web application are the exact same ones you’ll see using Business Central. Here is the Mortgage application form displayed in Business Central, compare it to the one shown at the top of this article. They are the same.



The business process used in this demo is the BPMS Example business process “Mortgage Approval Process” which is the same as that used in the previous article. To recap: The mortgage application begins at the start node by using a graphical form designed with the graphical Form Designer of BPMS to input data from the loan applicant, which includes the applicant’s personal information, annual income, social security number, the address and price of the property, and the down payment. Tasks encountered during the business process execution include: Validation, Data Correction, Credit Report, Mortgage Calculation, Appraisal, etc. The business process involves a total of 9 forms. The example Mortgage application uses server-side input validation ie, the form input is not validated on the client side. If client-side input validation is required, the Mortgage Business process, specifically the forms, will have to be modified. When that happens, client-side validation code has to be added to the JSP pages.

Here is the partial html/Javascript to kick off an instance of the home mortgage business process:

<script type="text/javascript">

// This function submits the form and start the process on the given div
function startProcess(divId) {

   // callback function that will be called after the process is started
   var onsuccess= function(msg) {
      // cleaning the container div & reseting the api

   // callback function that will be executed if an error occurs obtainging the form.
   // this function will receive the server response and will open an alert showing it.
   var onerror = function(msg) {
      alert("Error starting process: " + msg);
      // cleaning the container div & reseting the object status
   jBPMFormAPI.startProcess(divId, onsuccess, onerror);

   <div id="instructionDiv">
      <a href="#" onclick="showStartProcessForm();">Click here if Mortgage Application Form does not appear</a><br><hr><br>

   <div id="startProcessDiv" style="display: none; height: 600px; width: 800px;"></div>
   <div id="buttonsDiv" style="display: none;">
      <input type="button" value="Submit Application" onclick="startProcess('startProcessDiv')"/>


When a user clicks on the “Submit Application” button, the startProcess function is invoked with the name of the <div> that the form is to be displayed in. The startProcess calls the jBPM Form API to start a process instance in the way described in the UML sequence diagram shown earlier.

The jbpm-forms-rest-integration.js only deals with the form interaction part of your application. As for getting a list of tasks from BPMS, you have to set up your own REST API call and display the returned content. To do this, I set up an AJAX call to the Task REST API: rest/task/query?potentialOwner={currentUser} and format the returned data into a table.

Note that if your BPMS server is running on a different machine, your Javascript is actually calling the services on a different machine that your web application is running on. The approach will only work with Single Sign On. Otherwise it may run into cross domain scripting issues if the BPMS server and the web application are running on servers on different domains.


You can access this demo application here.

Use the menu at the top to interact with the Mortgage business process. The menu items include:

  • Home – displays this article
  • Mortgage Application – allows you to start an instance of a mortgage application by filling in a form (from the BPMS Server)
  • Task – lists the tasks that you can work on, click on “Show task form” to show the task form you select
  • Logout – only shows if you have already logged in to the application

To log in, you use user: user and password: userPassword|23

Loan Application Form
Loan Application Form


This demo application illustrates the use of the new Javascript jBPM Form API to interact with BPMS forms on a BPMS server. Its application architecture is quite different from that in the code generation approach described in a previous article. Using this approach requires only 2 JSP pages to interact with BPMS forms: one to start a business process instance and the other to show the task list and allow the user to show and interact with arbitrary task forms. All of these interactions are achieved using Javascript only.

By using the Javascript API, we avoided replicating the forms on the web application like that used in the code generation approach. Even when new task forms are added, the application using the jBPM Form API does not need to be changed. It just continues to work without needing rebuild or re-deployment. Contrast this to the code generation approach where the new form has to be generated and the application rebuilt and re-deployed. Does this mean that the code generation approach is obsolete now that the new jBPM Form API API is available on BPMS? Not necessarily. The pros and cons of using the Javascript approach vs the code generation approach are summarised in the table below to help you pick the approach that will suit you:

jBPM Form API Approach Code generation Approach
Architecture the logic is running on the browser the logic is running on the server
Simplicity only two JSPs to handle form interaction: one to start a mortgage application process instance and one to list all tasks and invoke and interact with a manual task form requires N + 2 JSPs (forms), N is the number of human task forms plus 1 for starting a mortgage application process instance and another one for listing all tasks. Since all forms and handling code are generated, this is not a deal breaker
Look and Feel not easy to control from BPMS especially for customers who want to provide their business processes as white-label services for paying clients who need to re-brand them with specific look and feel easy to control from the web application itself
Maintainability and Extensibility: adding and removing task forms not affected by addition or removal of task forms. The application will continue to work without modification requires regeneration of forms and a re-deployment
Security if the web application and the BPMS server are to be run on machines in different domains then a Single Sign On (SSO) facility has to be present, otherwise the Javascript API will not work due to cross domain scripting issues web application can use a different authentication and authorisation mechanism from that used by BPMS and SSO is not mandatory
Performance the forms come up noticeably slower the forms (local to the web application) come up much faster

It is your job as a Solution Architect to assess the pros and cons and pick an approach that will best suit your business requirements. It is horses for courses.

10 thoughts on “Building a JBoss BPMS Web Application using jBPM Form API”

  1. This design is steller! You certainly know how to keep a reader amused. Between your wit and your videos, I was almost moved to start my own blog (well, almost…HaHa!) Fantastic job. I really enjoyed what you had to say, and more than that, how you presented it. Too cool!

    1. Thanks Renita. Hope I can keep you amused with my forthcoming posts. Not a bad idea to start your own blog :-)

  2. It’s really a great and useful piece of information. I’m glad that you shared this useful info with us. Please keep us informed like this. Thanks for sharing.

  3. Hi there would you mind letting me know which webhost you’re utilizing? I’ve loaded your blog in 3 different web browsers and I must say this blog loads a lot quicker then most. Can you recommend a good internet hosting provider at a honest price? Many thanks, I appreciate it!

Comments are closed.