This documentation is about a version that is out of support, here is the latest documentation version.

How about downloading a newer, supported version?

Bonita Rest API Extension archetype

A set of best of breed tools to develop and test Rest API Extension independently of Bonita Studio.

REST API Extensions examples

A REST API Extension example resource and API extension viewer page are provided in the Administrator Portal, in the "Resources" section.

To use the examples, define a custom permissions mapping for demoPermission:

In a Tomcat bundle:

  • Retrieve platform configuration using the setup tool.

  • Edit platform_conf/current/tenants/<TENANT_ID>/tenant_portal/custom-permissions-mapping.properties.

  • Add the following line: profile|User=[demoPermission].

  • Push the changed platform configuration into database using the setup tool.

  • Restart Tomcat bundle

In Bonita Studio:

  • Open the custom-permissions-mapping.properties from Development menu > REST API Extensions > Edit permission mapping

  • Add the following line: profile|User=[demoPermission]

  • Save the file

  • Logout from the current session and log back in

REST API Extensions examples show how to:

  • Customize response with additional header, cookie and response code

  • Get resource return a simple echo of query parameters

  • Use a SLF4J logger

  • Post resources with Json payload and return a simple echo of parameters

  • Return an XML content with specific media type and character set

  • Call to external SOAP webservice (requires internet connexion)

Another REST API Extensions example with SQL data source is available on Bonitasoft Community. This example shows how to execute SQL queries on a external database.

Create a REST API Extension

Bonita offers the possibility to extend the set of existing REST API with custom extension that let you enrich your forms and applications with specific needs. They can be used to query business data, Bonita Engine APIs, or an external information system (such as a database, web service, LDAP directory…​). They also help to keep a clean separation between the front-end (forms, pages, and interfaces visible to users) and the back-end (processes). We provide a Maven archetype to help you to bootstrap a REST API Extension project. The source code of the archetype is available here.

Prerequisites

  1. Java 8 must be installed: https://adoptopenjdk.net/index.html

  2. Maven must be installed: https://maven.apache.org/install.html

  3. Rest API Extension development requires some software development skills. The archetype offers the possibility to develop the connector in Java, Groovy or Kotlin. Make sure that you are comfortable with at least one of those three languages.

  4. An Internet connection with access to Maven central repository

Generate the project using the Maven archetype

A maven archetype is a maven project templating toolkit. This archetype allows you to bootstrap a Bonita Rest API Extension project on your file system. A Bonita Rest API Extension project is a maven project. It can be built, tested and then deployed into a Bonita runtime using Bonita Portal.

To create your Rest API Extension project, prompt a terminal and enter the following command:

Make sure that you are not executing the command from an existing maven project.

 
$ mvn archetype:generate -DarchetypeGroupId=org.bonitasoft.archetypes -DarchetypeArtifactId=bonita-rest-api-extension-archetype

You’ll then have to specify interactively the properties of your project.

Archetype properties

Parameter Required Default value Description

-DbonitaVersion

true

You can choose the version of the dependent bonita artifacts. Minimum version is 7.0.1.

-Dsp

false

false

If set to true, project will use Bonita subscription dependencies. This implies you have made bonita subscription artifacts available for maven (in your local repository or enterprise repository)

-Dlanguage

true

You can choose between groovy, java or kotlin.

-Dwrapper

false

true

If set to true, project will setup a maven wrapper

-DapiName

true

Set the name of your api extension. You must enter an url friendly name without blanks.

-DapiDisplayName

true

A display name for your api extension (displayed in the portal for the administrator)

-DapiDesc

false

My Rest API extension description

A short description of the purpose of your api extension (displayed in the portal for the administrator)

-DhttpVerb

true

The http verb of your api extension

-DpathTemplate

true

URL path template. Resulting url: ../API/extension/myRestExtApi

-DpermissionNames

false

myRestAPIPermission

Define permission list (comma separated value), specify permissions a user need to have in order access this REST API extension

-DurlParameters

false

!

Define a list (comma separated value) of url parameters.

-DbdmGroupId

false

!

Define a BDM groupId name to enable BDM dependencies

-DbdmVersion

false

!

Define a BDM version name to enable BDM dependencies

⚠️ You can avoid the interactive mode by specifying all properties of your project directly in the command line, but by doing that you’ll bypass the validation performed on the properties content.

Generated project

A folder named [your artifact id] is created, with your Bonita Rest API Extension project, ready to use. Using the terminal you can cd into this folder and run:

$ ./mvnw

It should build and test the generated api sample. The result of this build is a .zip archive that can be retrieved in the target folder of the project. You can deploy this API extension archive using Bonita Portal.

Deployment

To deploy the REST API Extension:

  1. Go to the Administrator Portal

  2. Click on Resources

  3. Click on the Add button

  4. Select the previously created .zip file

  5. Click on Next

  6. Click on Confirm

Use in applications

A REST API Extensions must be deployed before any page or form resource using it is deployed.

A page that uses REST API Extensions must add the required resources in the page resource page.properties file. For example, if a page uses the demoHeaders, demoXml, and putResource API extensions, its page.properties must include this line:

resources=[GET|extension/demoHeaders,POST|extension/demoXml,PUT|extension/putResource]

If the page declares its resources correctly, then every user able to access this page (because they have the right profile for the Living Application) will also be automatically granted the necessary permissions to call the REST API Extensions. This works the same way as with the other resources of the REST API.
However, if you need to grant access to this REST API Extensions to some users regardless of the pages they have access to, then you need to add custom permissions for these users.
In order to do so, edit custom-permissions-mapping.properties to give the permissions (value of the property apiExtension.permissions) declared in the page.properties of the REST API Extensions to the required profiles or users.

REST API permissions are stored in the user’s session and new permissions will only be effective for a user the next time they log into Bonita Portal.

In Bonita Studio, the debug mode is disabled by default. In debug mode, you can see changes on your REST API Extensions without importing a new .zip archive, but it means the classloader of the extension is recreated at each request.
If you want to enable the debug mode, you can activate it in Bonita Studio "Server" preferences.

Configure the authorization

To configure the REST API authorization, checkout the dedicated documentation page. Note that you can reuse existing permissions that are already mapped to provided profiles (User, Administrator).