WSO2 Enterprise Integrator 5 min

How to invoke a BPMN process from the WSO2 Enterprise Integrator

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
yenlo blog 2020 07 30 how to invoke a bpmn process from the wso2 ei 600x350

How to invoke a BPMN process from the WSO2 Enterprise Integrator Not all processes are synchronous. By synchronous I mean: you sent a request to a backend service and you get a direct response. Let’s say that you have an API which will get you the weather in Amsterdam today. You basically look at the API and see what kind of parameters it takes. It can be named the city and date. You invoke the API and within no time you get a response from the server with the temperature, and other information about the weather, whether it’s sunny, et cetera.


For example, there are situations in which you apply for a permit where you cannot provide a direct answer. Let’s say you request to make some extra payments, paying off your home’s mortgage. Someone may need to look at that request and make a manual calculation to see if it is possible and to determine the cost. In that case, we call that an asynchronous process, the response is coming (a little bit) later. This example with a mortgage or even a loan for that matter is a business process where they’re in many cases also human involvement, for instance a loan officer. He or she might look at your application and determine whether it’s possible or not.

To model these kinds of processes it’s possible to use the WSO2 Business Process Server (BPS). The WSO2 BPS is part of the WSO2 Enterprise Integrator (WSO2 EI) and is one of the products bundled with it. This makes it a product that is optional to use. When you start the WSO2 EI, the Business Process Server doesn’t automatically start. You have to do that separately. It’s set up so that you can run the WSO2 EI with the Business Process Server on the same server, without any port collisions, because the Business Process Server, has a port offset of 2 by default, and therefore doesn’t conflict with the WSO2 EI.

What the WSO2 BPS does is that it supports WSO2 Business Process Modelling and Notation (BPMN) (subset of it), Web Services Business Process Execution Language (WS BPEL) and human tasks. And I would like to focus on BPMN as the language to define processes. This is not going to be a blog with in-depth descriptions on pools, swim lanes, parallel processes, and everything else you normally encounter when working with the BPS. No, what I would like to show you is that when I create a simple process, for example a process where certain data needs to be filled in and approved, I can start that process programmatically.

So how do you define BPMN processes. Well, this is done using the WSO2 Integration Studio, where there is something called a BP project, and a BP project is a project that allows you to create a nice BPMN in process.


So, we’re going to focus on BPMN and what I’m going to do is pretty straightforward. I’m going to define a process that takes up a couple of values and then passes those values through variables during the execution of the process.


When you look at the product itself, it uses Apache’s Activiti engine to support the BPMN processes. When you compile or you export the file, it becomes a .bar file that you need to upload to the Business Process Server using your management user interface (UI). The BPS admin interface allows you to upload it and then there is a BPMN Explorer interface, which shows you the processes, the tasks, et cetera.

I must say that when I worked with the product for this blog, I got excited about the possibilities and how you can connect to it. It’s only been once that I’ve done the training, which is more than four years ago, when the Business Process Server was originally a separate product from WSO2.

The use case is that the process starts with entering data (Student Number, Student Name and Student Grade) and submitting it. A clerk will approve it manually. It’s therefore a human task to review the submitted information. And then approve or reject the application. And if approved it actually goes to another system that takes care of the enrollment for a fairly simple use case. And of course it’s very easy to mock such a situation. So creating APIs and stuff like that is no big deal.

I created a very simple BPMN process with a simple start and finish and with a human task in the middle, the input.

Figure 1 BPMN Process



What you’re going to get is either manual input when you start the process from the Explorer interface, or you basically add the parameters to the API POST payload that you’re going to send to the service.

Deploying it

Figure 2 Activiti Explorer

The first step is to create the bar file which encapsulates the BPMN file that is parsed and executed on the BPS. This is done in WSO2 Integration Studio, where you can create the deployment artifacts. For this you need to be in Activity View.



We add the BPMN package or the BAR file to the Business Process Server using the management UI. Here we can visually check if the package has been properly deployed.


Invoke the process

Now let’s invoke the admission process. To do this we are going to use the BPMN Explorer where we can see the deployed processes in the bar files.


By clicking on start to admit new students, I’m actually kicking of that process.

Figure 3 Enter Student Number, name and grade

This starts the process.


We can see the process.


The clerk sees the task in the overview.


And can complete it.


The task is now gone.

Invoking with REST

When we use SOAPUI to call the service, we define a rest project for this URL: https://localhost:9445/bpmn/runtime/process-instances

These are the parameters, partly those for the process, but also for defining the process to be called.

"variables": [
"name": "studno",
"value": "1000000"
"name": "studname",
"value": "120000"
} ,
"name": "studgrade",
"value": "9.9"
"processDefinitionKey": "Admission",
"tenantId": "-1234"

Keep in mind that the call is a POST with a JSON payload and that we need basic authentication for this (admin / admin).

We do get a response from the server and can see the invoke process again with a task for the clerk.


In this blog, I showed you that you were able to create a BPMN process and programmatically invoke the process using a rest API. I chose a very simple example for this blog because the BPMN language and the tooling available in WSO2 Integration Studio requires a bit of learning as far as the configuration goes. I used the documentation available from WSO2 to create this example and help from my colleague Dusan Dević, whom I owe a lot of gratitude.

Microservices for the Enterprise

Get it now
What's on our menu