Bonita Rest API Extensions


Bonita is an open and extensible application platform that takes an API first approach to the design and development of business processes. Bonita leverages REST APIs to facilitate interactions with the core of its business process management capability. Everything from creating users, deploying processes, acquiring and actioning tasks is accomplished through the provided REST APIs. This is a great asset of the solution however you may hit a roadblock when you need to do something outside of the default APIs. This is where REST API extensions come into play. They are deployed into the Bonita runtime platform and can be invoked in exactly the same way as the default REST APIs provided by the system.

The subscription editions of Bonita provides integrated development capabilities into the Studio designer, however this blog post will explain how to setup a framework based on industry standard java and maven tooling which can be used in both the community and subscription editions.

The following sections walk you through:

  • Setting up the project structure
  • Creating a simple REST API extension
  • Deploying the REST API extension to an existing (community or subscription) Bonita server
  • Invoking the REST API extension

Set Up

Rather than walking you through all the nitty-gritty details of setting up a maven project from scratch, you can head over to on github and simply download or clone the repository. This section assumes that you have done this and will provide only a summary of the key files.



src/main/resources/ – The main configuration file for a REST API extension. It contains the following details for each REST API extension endpoint:

  • HTTP method
  • Entry point groovy class (which in this case, points to
  • Security (which for now we will configure to allow access to all users)


  • RestApiEntryPoint.groovy – The groovy entry point for the REST API. Note that bonita requires that the entry point be a groovy class. However, since we will be using java for the core of the REST API, a simple groovy class which extends a java class is used
  • – The core java entry point of the REST API which extends BaseRestApiExtension ensuring that the appropriate doHandle method is implemented
  • – Defines the response structure

Creating a simple REST API extension

Rather than create a new REST API extension from scratch, we will copy the existing templateRestApi directory and name it sampleRestApi. Once copied, perform the following:

restApiExtensions/pom.xml – Add the sampleRestApi as a module:



sampleRestApi: pom.xml – Update the artifactId, name and description tags:

<description>Sample REST API</description>


src/main/resources/ – Update references to templateRestApi with sampleRestApi:

description=Sample REST API



  • Rename to and update references in the source code appropriately
  • Rename to
  • – Update to extend SampleRestApi


  • Rename to SampleRestApiTest and update references in the source code appropriately

Writing the custom code

So far, we’ve explained how to create the structure of a bonita REST API and in this section we will provide an example of some code which interacts with the bonita engine. In particular, we are going to modify our sample REST API to return the details of the user invoking the API and also a list of tasks which are assigned to them.

So to start, let’s update the SampleRestApiResponse class to define the desired response fields:


import org.bonitasoft.engine.bpm.flownode.HumanTaskInstance;
import org.bonitasoft.engine.identity.impl.UserImpl;
import java.util.List;

public class SampleRestApiResponse {
    private UserImpl currentUser;
    private List<HumanTaskInstance> humanTasksAssignedToCurrentUser;

    // getters and setters omitted for brevity


The UserImpl and HumanTaskInstance classes represent the user and task objects respectively.

In order to retrieve the current user details, we will utilise the following:

long currentUserId = restApiContext.getApiSession().getUserId();
UserImpl currentUser = new UserImpl(getIdentityApi().getUser(currentUserId));


In the above, the getIdentityApi method provides access to bonita’s identity API which provides numerous methods to interact with bonita’s user, group, role and membership objects. In this case, we are retrieving the current user ID from the API session and then creating a new UserImpl object representing the user.

To retrieve the list of tasks assigned to the user, we will use bonita’s process API and search for tasks which are assigned to the current user:

SearchOptions searchOptions = new SearchOptionsBuilder(0, Integer.MAX_VALUE).filter(HumanTaskInstanceSearchDescriptor.ASSIGNEE_ID, currentUserId).done();
SearchResult<HumanTaskInstance> humanTasksAssignedToUserSearchResult = getProcessApi().searchHumanTaskInstances(searchOptions);
List<HumanTaskInstance> humanTasksAssignedToCurrentUser = humanTasksAssignedToUserSearchResult.getResult();


If you wish to check out the completed code for the sample REST API check out the sampleRestApi branch on github:

Building REST API extensions

To build the sample REST API, navigate to the restApiExtensions directory and run the following:

mvn clean package --projects sampleRestApi --also-make


This will produce a zip file named sampleRestApi-1.0-SNAPSHOT.jar within the sampleRestApi/target directory which we can deploy to a bonita server as outlined below.

Deploying REST API extensions

In order to deploy the REST API extension, open a browser and login to the bonita portal (e.g. http://localhost:8080/bonita) as a user who is an Administrator. Navigate to the ‘Resources’ tab and then click ‘Add’. Select the built REST API extension zip file and click ‘Next’ and then ‘Confirm’. The REST API extension should now be deployed and you should be able to invoke it by simply navigating to the appropriate endpoint (e.g. http://localhost:8080/bonita/API/extension/sampleRestApi) which will return a response similar to the following:

"currentUser": {
        "id": 4,
        "firstName": "Walter",
        "lastName": "Bates",
        "password": "",
        "userName": "walter.bates",
        "iconId": null,
        "title": "Mr",
        "jobTitle": "Human resources benefits",
        "creationDate": "2018-04-24T14:09:53.666+1000",
        "createdBy": -1,
        "lastUpdate": "2018-04-24T14:09:53.666+1000",
        "lastConnection": "2018-04-27T07:30:10.129+1000",
        "managerUserName": null,
        "managerUserId": 3,
        "enabled": true
    "humanTasksAssignedToCurrentUser": [
            "actorId": 1,
            "assigneeId": 4,
            "priority": "NORMAL",
            "expectedEndDate": null,
            "claimedDate": "2018-04-27T07:30:42.250+1000",
            "parentContainerId": 1,
            "state": "ready",
            "stateCategory": "NORMAL",
            "rootContainerId": 1,
            "processDefinitionId": 7629126156073007208,
            "parentProcessInstanceId": 1,
            "displayDescription": null,
            "displayName": "Review task",
            "description": null,
            "executedBy": 0,
            "executedBySubstitute": 0,
            "flownodeDefinitionId": 5946836920024332147,
            "reachedStateDate": "2018-04-27T07:30:24.792+1000",
            "lastUpdateDate": "2018-04-27T07:30:24.792+1000",
            "name": "Review task",
            "id": 2


Intelligent Pathways is a Bonita Premier Partner with several years of experience implementing Bonita processes, connectors and REST API extensions.

Author Details

Kevin Henshall
Kevin is an Integration and Automation Consultant with over 12 years experience. As Intelligent Pathways’ principal Automation consultant, Kevin is highly experienced working with multiple automation technologies, including RPA tools UiPath, Microsoft Power Automate and BPM. Initially specialising in the design, development and integration of enterprise applications, Kevin also has in-depth knowledge of middleware and integration practices. Kevin is known for his exceptional eye for detail, and his ability to distil complex business processes into efficient and robust automated solutions. Kevin has worked in agile environments and is comfortable liaising with a variety of stakeholders including project managers, end users, testers and other developers.

You might be interested in these related insights