REST API Extensions

This page describes how to deploy a REST API extension manually, which is possible with all editions.
A REST API extension allows to extend REST Resources using Bonita, to get or send information in a page or a form.

To learn more on how to create REST API Extensions, refer to the tooling for creating and testing REST API Extensions page (Subscription editions).

Deploy a REST API Extension

REST API Extensions are managed as resources.

REST API Extensions use the same authorization mechanism as the standard Bonita REST APIs. When you import the extension, the information in page.properties is used to create the appropriate resource permission mappings in Bonita (see REST API authorization for information about REST API security configuration).

It is also possible to deploy a REST API Extensions using REST portal API / "page" resource.

The deployment of the REST API Extensions should always be made from Bonita Administrator Application or its APIs, not directly from Engine APIs. Notably, the createPage() method of the Engine PageAPI would allow you to deploy a REST API Extensions, but would not update the security settings, meaning that you would not be able to access it at runtime.

If you are running Bonita in a cluster, after you import a REST API Extensions, you must restart the application server on all the cluster nodes.

As the deployment of the REST API Extensions automatically creates the appropriate resource permission mapping, be careful not to push a configuration that does not contain the latest permissions updates. This would overwrite the deployed configuration. To avoid doing so, pull the latest configuration, edit the needed elements and push it back to the Bonita runtime in a pretty short amount of time.

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.

If the page declares its resources correctly, then every user being able to access this page (because it is part of a custom profile or Living Application they have access to) 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.

Live update

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 the Studio server preferences.

Live update allows the Administrator to update one element of the application in a situation of emergency.

Edit the REST API extension

  • Retrieve platform configuration using the setup tool.

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

  • Add a permission for the REST API: profile|User=[examplePermission].

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

  • Restart Tomcat bundle

You can edit the content of a REST API extension by installing a new version. The url mappings in the page.properties in the new version should have the examplePermission.