Manage process dependencies

Learn how to manage dependencies using Bonita Studio, so that when you build a process for deployment, all the dependencies are included

A dependency is an external module, not provided by the Bonita runtime, that is used by a process. It can be an extension or any third party jar to you may need in your process.

You can have an overview of your project dependencies using the project Overview in a Bonita Studio. From there you can navigate to the Extensions view. This view only displays the root dependencies. In most cases, a java dependency has transitive dependencies. Bonita Studio helps you deal with those transitive dependencies by using Apache Maven as a dependency management tool for your Bonita project.

Configure process dependencies

Once you have added the required dependencies for your project. You need to add them to the process configuration that will use them.

To specify the dependencies for a process, select the process and click Configure in the toolbar. Navigate to the Process dependencies tab.

If your process already uses some connectors or actor filters. You’ll see that connectors and filters dependencies are automatically added to the configuration. Now if you need a specific dependency you can select the Other category in the dependency tree and click Add…​. It opens a dialog with the root dependencies declared at the process level. Select your dependency and click OK.

It is at this time that if a root dependency have transitive dependencies, they are automatically added in configuration.

Dependencies conflicts

You can have to deal with dependency conflict when adding dependencies in a process configuration. A warning is displayed on jars that are already presents in the Bonita runtime and that may cause issue at runtime. If the dependency version is the same between the Bonita runtime and your dependency you can delete or deselect the corresponding jar from the dependency tree of the Process dependencies tab. If they are not in the same version, you can opt to leave both versions but it is highly recommended to align the conflicting dependency version with the one provided by the Bonita runtime.

Incompatible dependencies

The Bonita runtime already comes with provided dependencies. If you try to add a dependency that is not compatible with the provided dependencies you may have some errors on your project pointing the relevant dependency. The common incompatibilities are by example a dependency that requires groovy-all or bonita-server. Those are already provided by the runtime and thus, should not be added to the project classpath. To fix those issues, you must update the source code of the dependency and declared the dependencies that are already in Bonita runtime with a provided maven scope.

Avoiding dependency conflicts

If you want to develop custom extensions for your processes, it is highly recommended to use Maven projects and the import the runtime BOM (Bill of Material) in the <dependencyManagement> section of your project:

 <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.bonitasoft.runtime</groupId>
        <artifactId>bonita-runtime-bom</artifactId>
        <version>${bonita.runtime.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

This will help Maven selecting the matching versions if you are using a dependency already available in the Bonita runtime. When it is the case a warning should be displayed by your IDE. You can remove the version and set the scope to provided.

Troubleshooting

Missing dependencies in my configurations after a project migration

When a project is migrated the target runtime version is updated and some provided dependencies may changes (version update or dependencies removed). In some cases, one of your extension may have missing transitive dependency because the provided version provided by the runtime is not the same as the one expected by the extension. You can mitigate this issue by:

  • Removing this dependency from your configurations. The runtime dependency version will be used at runtime.

  • Explicitly add this dependency in your extensions with the required version (Project Overview > Extensions > Add a custom extension > Other…​).

Both workarounds are not ideal.

In the first case there is a risk that the version provided by the runtime is not compatible with the extension. You will also be more at risk with further version update if the provided dependency is updated/removed as it will be only be detect at runtime.

In the second case you might have classloading issues as two versions of the same dependency are loaded in your runtime classloader. Bonita supports to a certain extent this scenario but there are edge cases not properly supported (eg: sl4j-api static factories…​etc). In addition, when your extension is updated, that transitive depencency version might become irrelevant.

The recommendation is to properly test your extension against the target runtime version to guarantee a proper dependency management is done on the extension side. Make a new release of your extension if required when updating from one bonita runtime version to another.

Example: My extension required commons-lang3 in 3.11 version and it’s working fine in 2021.2. I update my project to 2022.2 and now I got missing dependency configuration errors for commons-lang3-3.11.jar. In 2022.2 the commons-lang3 dependency has been updated to 3.12.0 so I need to update the version of commons-lang3 in my extension and make a new version compatible with 2022.2.

It can be done by updating to the bonita-runtime-bom to 7.15.0 when your are using the BOM in your extension.