REST API Overview with a Getting started example
The REST API lets you access the data with HTTP requests; it is useful when implementing rich web forms / pages for a good user experience.
Api documentation
Overview
If your application is using a technology other than Java, you can integrate it with the Bonita solution using the Web REST API. This API provides access to all Bonita objects (like processes, tasks, users, connectors etc.), to execute operations on them (create, retrieve, update, delete). You can use these operations to create a workflow with Bonita and integrate it into your application. The Bonita Engine remains responsible for executing the workflow logic (connectors, gateways with conditions, messages, timers etc.) while your application gives access to the workflow. Users can manage processes and tasks, and perform administrative activities.
Access to the Web REST API depends on REST API authorization settings.
Execute REST calls and integrate the results in your application
After the application is connected to the Bonita Engine, you can start calling API methods. The following is a typical scenario for an end user.
-
Start a new case with variables: Provide a form for the user to enter initial data. Then call the method to start a new case using the values entered by the user to initialize some variables. The engine will start the execution of the process. Depending on the design of your process, there might then be some human tasks available for the end user.
-
List the pending tasks for a user: Retrieve a list of available human tasks for the logged in user. When the user selects a task to do, you can display the corresponding form. It can be an external form or a Bonita form that can be accessed by url.
-
Update variables and execute a task: If your application is using an external form, update the values of the variables in your process. You can use a method to update process or activity variables with values coming from your application. When the user submits the external form, you can call a method to execute a task. The engine will then continue the execution of the workflow as designed.
-
Handle tasks in error: Get a list of tasks that are in the failed state, and then replay each task by doing three steps: get the list of failed connectors, reset the state of failed connectors and replay the failed task.
Troubleshooting
HTTP/1.1 401 Unauthorized
If the HTTP response’s status is 401 Unauthorized:
-
make sure that the cookies have been transferred with the call
-
make sure that the cookies transferred are the ones generated during the last successful login call
-
if one of the PUT, DELETE or POST method is used, make sure that the
X-Bonita-API-Tokenheader is included -
if the X-Bonita-API-Token header is included, make sure that the value is the same as the one of the cookie generated during the last login
-
Maybe a logout was issued or the session has expired; try to log in again, and re-run the request with the new cookies and the new value for the
X-Bonita-API-Tokenheader.
HTTP/1.1 416 Content Range Not Satisfiable
If the HTTP response’s status is 416 Range Not Satisfiable:
This error can happen on search requests with pagination when a firewall is blocking the response.
Bonita REST API is using the content-range response headers to return pagination information and some firewalls may prevent this usage.
-
If you have a firewall with an option "Allow HTTP partial response" in its configuration, make sure it is enabled at least for you Bonita runtime server address.
-
Make sure your firewall or your reverse proxy doesn’t have any other option that could block this response header