How to use the BonitaSoft Engine API with Spring Boot

In this article we are going to develop a restful service with Spring Boot and the Bonitasoft Engine API, this service will return a list of users that are within the organization that we have by default in Bonita Studio 7.11.

If you do not know how to use Spring Boot you can see this tutorial where we create a Restful API with the basic operations of CRUD.


To develop this service we are going to use 3 tools:


We are going to divide the development into 3 sections:

1. Create and load the project in Spring Initializr

We should go to Spring Initializr and create a project with dependency Spring web, this unit will help us with the whole restful topic and then we click on the button GENERATE:

This will download a file .zip, we look for it in the finder / explorer and unzip it:

We open our SDI and we load the project, in my case I am using IntelliJ Idea:

We search for the project and open it:

After loading the project we should have something similar to this:

2. Creation of services integrated with the Bonitasoft Engine API

Before starting with the development, we must open the Bonita Studio so that it raises the pretty engine and we can connect later, we will see that by default we will have an organization created and there are the users that we will return from our service:

Again we go to our SDI and we are going to open the file Pom.xml to add the following dependencies:

 org.bonitasoft.engine  pretty-client  $ {bonita.bpm.version} 

We must also add the following property:


We must place the above in the following sections:

Now we are going to go to our main package that is inside src> main> java and we are going to create 2 packages inside com.example.demo, these packages are going to be:

  • Service: Here we will create the service with all the logic to connect to the Bonita engine and obtain the list of users.
  • Controller: Here we will create our @RestController where we will expose the services of the service package and create a endpoint functional.

Inside the service package we are going to create the class EngineService, within this class we are going to create our service and we are going to connect to the bonito engine and we will obtain the list of users:

package com.example.demo.service; import org.bonitasoft.engine.api.ApiAccessType; import org.bonitasoft.engine.api.IdentityAPI; import org.bonitasoft.engine.api.LoginAPI; import org.bonitasoft.engine.api.TenantAPIAccessor; import org.bonitasoft.engine.identity.User; import org.bonitasoft.engine.identity.UserCriterion; import org.bonitasoft.engine.session.APISession; import org.bonitasoft.engine.util.APITypeManager; import org.springframework.stereotype.Service; import java.util.HashMap; import java.util.List; import java.util.Map; @Service public class EngineService {public List  getUsers () {try {Map  map = new HashMap  (); map.put ("server.url", "http: // localhost: 8080"); map.put ("", "nice"); APITypeManager.setAPITypeAndParams (ApiAccessType.HTTP, map); String username = "walter.bates"; String password = "bpm"; LoginAPI loginAPI = TenantAPIAccessor.getLoginAPI (); APISession apiSession = loginAPI.login (username, password); IdentityAPI identityAPI = TenantAPIAccessor.getIdentityAPI (apiSession); List  users = identityAPI.getUsers (0.50, UserCriterion.USER_NAME_ASC); return users; } catch (Exception e) {e.printStackTrace (); return null; }}}

We are going to explain the code line by line. The first thing we do is add the directive @Service to tell Spring that we are creating a service. Then we will create a method that will return a List (Here it is important that the User type comes from org.bonitasoft.engine.identity.User), do not forget that we must add all the logic within the try-catch to catch any exceptions that come up. The code to obtain this list of users can be divided into 3 blocks:

Block #1 - Definition of server.url, and HTTP connection method

We must create a Map where we will add the url and the server port where the bonito engine is running (in our case it is localhost and the port 8080) and the name of the application, be it map we are going to send it inside a APITypeManager to indicate that we are going to connect via HTTP to the url and application indicated on the same map.

Block #2 - Authentication

In this second part we must create the variables to store the Username and Password of the user with whom we are going to authenticate ourselves in Bonita, for this example we are going to use the user "walter.bates" and the password is "bpm". Then we will get the LoginAPI which will later allow us to create a APISession which will be used in block 3.

Block #3 - Let's get the users

With the session created in block 2 we will obtain the IdentityAPI, this API allows us to manage topics that have to do with the organization of Bonita, that is why we use it to obtain a list of users with the method getUsers () and finally we return this list.

Now we are going to go to the controller package where we will create the EngineController class:

package com.example.demo.controller; import com.example.demo.service.EngineService; import org.bonitasoft.engine.identity.User; import org.springframework.http.HttpStatus; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.List; @RestController @RequestMapping ("/ demo") public class EngineController {private EngineService engineService; public EngineController (EngineService engineService) {this.engineService = engineService; } @GetMapping public ResponseEntity  > getUsers () {return new ResponseEntity  > (this.engineService.getUsers (), HttpStatus.OK); }}

In this class we are going to indicate to Spring that he will be ours @RestController, then we define our path in «/ demo» with @RequestMapping. We expose the previously created service and create a method that will respond by a Get method and we will call it anyway getUsers () that the list of users will return to us by means of a ResponseEntity with a status 200 OK.

With this we have our restful service built to 100%, now we are going to tell you why port we want our project to run since by default it will try to run by 8080 but this is already being used by Bonita Studio and an error will appear. Inside the src> main> resources folder create the application.yaml file to configure the port:

server: port: 8081

You can also configure it within the file that comes by default:

#Server Port server.port = 8081

3. Execution and consumption of the service

To execute our project I am going to add a configuration in our SDI:

After this we click Apply and then OK. We just need to run the project:

We wait for our service to run and lift correctly:

Finally we are going to consume our service by sending a request from Postman:

The service works correctly, it returns the list of users that we indicate without problems. The source code of this project can be obtained here:

I also leave you the video of this whole procedure:

I invite you to tell me in the comments what you think of this tutorial and what other example of Spring Boot or the Bonitasoft Engine API you would like to see.

The importance of the and how to build it

Many developers tend to have many projects in git repositories on services like GitHub, Bitbucket or GitLab. It is normal to see that in the vast majority of these projects that a blank file exists or is even non-existent, that is why I am going to tell you a bit about its importance and how you can build your first

What is the file?

This file is where pertinent information about your project is placed, the version in which it is currently located, how it should be displayed, how to contribute, what requirements you should complicate for its use, among other things.


It is always recommended that you have good documentation on your projects and this file is no exception, I recommend that you update your readme as your project progresses and detail the information necessary for its use.

If it is an open source project, this documentation is almost mandatory as it will be the gateway for future contributors and grow the community you need for your project to prosper.

Example of a

We can see in very popular projects in the different developer communities that have a good readme, for example the Facebook React.js repository:

Markdown = .md

Markdown is a lightweight markup language with which you can build an enriched html structure giving it a more pleasing visual, which is why this format is used in git projects.

To use the Markdown format here I leave you the syntax so you can start:

Information taken from template

I leave you a template to reuse in your projects, in this way they add a plus that will be very helpful when working as a team:


To finish I recommend the following:

  • If you have not created a reame I recommend that you start at once and create your first readme in any project that you have in git. If you want, use the template that I shared and adapt it with the information of your project.
  • Customize and add more sections to your reame to make it amazing.
  • You can build on popular projects like the one I mentioned in this post.

If you have any questions or suggestions do not hesitate to leave it in the comments and we will take it into account.

Restful API creation with Spring Boot, Lombok and Swagger

A while ago I shared a guide on youtube on how to create a Restfull API with Spring Boot, Project Lombok and Swagger. I leave you here the guide so you can enjoy it and put any questions you have in the comments.

The guide consists of 3 parts in which we go from the creation of the project from Spring Initializr to the implementation and construction of the graphical interface with Swagger and Swagger UI. The final product will be to create the restfull services to perform a basic CRUD on the user entity.

Resources and tools to use


Project source code

You can get the project in my github profile or in the following link:

If you have any questions or suggestions do not hesitate to leave it in the comments and we will take it into account.

es_ESEspañol en_USEnglish