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 Maven dependency 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.
|
If you need to review all the dependencies associated with your project—or just a specific process—simply right-click on the desired element and select Dependency Tree. This will displays a comprehensive Maven dependency tree, detailing every dependency included in your 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 Java Dependencies tab.
The Java Dependencies page provides two views:
-
Hierarchical view: displays the full dependency tree organized by category (Connectors, Actor Filters, Other). Each JAR has a checkbox — checked means included in the BAR, unchecked means excluded.
-
Flat view: a flat list of all JARs with a search by name, showing the source category for each entry.
If your process already uses some connectors or actor filters, their dependencies are automatically added to the configuration. To add a custom library, select the Other category in the dependency tree and click Add…. It opens a dialog with the Maven dependencies available in your project. Select your dependency and click OK.
|
If a root dependency has transitive dependencies, they are automatically added to the configuration. |
When building the BAR file, only checked JARs are included in the archive.
Dependencies conflicts
The hierarchical view displays visual indicators next to each JAR name:
| Indicator | Meaning | Behavior |
|---|---|---|
(none) |
JAR is specific to your process, not present in the Bonita server |
Checked by default, user-modifiable |
"Exists in the runtime container" |
JAR is already present in the Bonita server with the same version |
Automatically unchecked and grayed out — cannot be modified |
"Exists in the runtime container with a different version" |
JAR is present in the Bonita server but in a different version |
Automatically unchecked and grayed out — cannot be modified |
Warning icon |
JAR is referenced in the configuration but not found in the project’s Maven dependencies |
Checked by default, user-modifiable |
JARs already present in the runtime are automatically excluded from the BAR to avoid duplication or version conflicts. This behavior is enforced and cannot be overridden.
|
To avoid compatibility issues, align your dependency versions with those provided by the Bonita runtime. See the Bonita runtime dependencies page for the full list. |
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.
Managing Environment-Specific Dependencies with Maven Profiles
Maven dependencies you add as extensions are available for all environments. But sometime, you may need different libraries depending on your environment configuration.
For this purpose, Bonita Studio supports managing environment-specific dependencies via custom Maven profiles.
By default, your project uses the active profile (e.g., the default profile here). You can define additional profiles for specific environments.
For example, consider a complex library mylib which has to connect to a complex system. In development phase, developers prefer using a stub library called mylib-stub that simulates it with lower costs and/or request times.
Below is an extract of a pom.xml that illustrates the default profile along with the env-Local using mylib-stub:
<profiles>
<!-- Default profile with actual library (active by default) -->
<profile>
<id>default</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<dependencies>
<dependency>
<groupId>com.mycompany</groupId>
<artifactId>mylib</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</profile>
<!-- Custom profile for a stub library -->
<profile>
<id>env-Local</id>
<dependencies>
<dependency>
<groupId>com.mycompany</groupId>
<artifactId>mylib-stub</artifactId>
<version>1.0.0</version>
</dependency>
</dependencies>
</profile>
</profiles>|
Make sure your environment profile is always named |
To build your project with your custom profile, run:
mvn clean package -Penv-Local|
Limit modifications to your pom.xml to avoid breaking compatibility with Bonita Studio or complicating future migrations. |
Troubleshooting
JAR version references after importing a .bos from an older version
When importing a .bos file created with a previous Bonita version, JAR references may point to versions that no longer exist in the project. The Studio automatically migrates these references by searching for another version of the same artifact in the project’s Maven dependencies.
This migration applies to all environments: the local .conf file and configurations embedded in .proc files (Qualification, Production, etc.).
If a JAR is no longer in the project’s Maven dependencies (for example, because it is now provided by the Bonita runtime), the wizard automatically detects it as a runtime dependency, grays it out, and excludes it from the BAR. No manual action is required.
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 It can be done by updating to the |