This documentation is for a version that is out of support.

You may want to view the same page for the latest version, or for any of the versions available in the drop-down menu in the top-right corner.

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 Portal 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 Bonita Portal.

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.

REST API Extensions examples

A REST API Extensions example resource and API extension viewer page are provided in administrator portal. They are located in administrator portal.

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

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 the following line: profile|User=[demoPermission].

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