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 Bonita Administrator Application, in the "Resources" tab.

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 the REST API Extensions contextual menu > 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 17 must be installed

  2. Maven must be installed

  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 Administrator Application.

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

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

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

If you are using Power Shell make sure to use quotes for the parameters: 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:

  • groupId: the group id of your REST API Extension.

  • artifactId: the artifact id of your REST API Extension.

    • Must match the following regex: ^[a-zA-Z0-9\-]$+

    • Example: my-rest-api

  • version: the version of your REST API Extension (default value: 1.0-SNAPSHOT) Follow the maven naming convention guide

  • package the package in which the source files will be created (default value: the group id of the connector)

  • apiDisplayName: the display name for your api extension (displayed in the Bonita Administrator Application)

  • apiName: the name of your api extension. You must enter an url friendly name without blanks.

  • bonitaVersion: the targeted technical Bonita version (e.g. 7.12.3)

    • A Bonita REST API Extension project depends on org.bonitasoft.engine:bonita-common. To avoid potential conflicts / errors at runtime, you should use the Bonita version of your runtime environment.

  • httpVerb: The http verb of your api extension (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE)

  • language: the language used in the connector project. Available values:

    • java

    • groovy

    • kotlin

  • pathTemplate: URL path template. Resulting url: ../API/extension/myRestExtA

Be sure to use the technical id of your Bonita version.

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.

Example:

mvn archetype:generate \
    -DarchetypeGroupId=org.bonitasoft.archetypes \
    -DarchetypeArtifactId=bonita-rest-api-extension-archetype \
    -DgroupId=org.company.api \
    -DartifactId=my-rest-api \
    -Dversion=0.0.1-SNAPSHOT \
    -Dlanguage=java \
    -DbonitaVersion=7.12.1 \
    -DapiName=myRestApi \
    -DpathTemplate=my-rest-api \
    -DapiDisplayName="My REST API" \
    -DurlParameters=p,c \
    -DhttpVerb=GET

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 verify

It builds and tests 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 Administrator Application.

Deployment at Runtime

To deploy the REST API Extension:

  1. Go to the Bonita Administrator Application

  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

Publication

To consume a Rest API Extension developed in an external project, it is recommended to publish it in a Maven repository (Nexus, Artifactory, Github package…​).

Please read the Maven deploy plugin instructions to configure your project for publication.

Import a Rest API Extension in a Bonita Project

When developing a Rest API Extension in an external project, you will need to import it as an extension in a Bonita Project.

If the Rest API Extension depends on a BDM model, it is mandatory to import it in a Bonita project providing the same BDM model.

  1. Go to the Bonita Project Overview in the Studio

  2. Click on Extensions

  3. Click Add a custom extension > REST API Extension…​

  4. Select the import mode:

    1. If the Rest API Extension is published on a remote Maven repository (Artifactory, Github package…​), select From a repository:

      1. Specify the artifact coordinate of the Rest API Extension

    2. If not, you may select From file. It will copy the extension archive in the target Bonita Project.

      1. Browse the extension archive file (*.zip) from the Rest API Extension project target folder

  5. Click on `Import `

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 the Bonita Runtime.

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).