Bonita Migration - 5X to 6XBonitasoft is slowly phasing out its revolutionary Bonita Open Solution V5 and urging its users to embrace newer versions of BPM software. As a Bonita user, if you are planning for a Bonita BPM migration, this is the right time. Further, migrating to a newer version helps users gain access to fascinating set of new features such as actor mapping, configuring parameters and environments. The newer versions also includes a feature rich design/development environment and makes the design and development process simpler.
Bonitasoft has been regularly coming out with newer and improved versions of their open source BPM tool. This blog post is for Bonita users who are keen to migrate to newer versions of Bonitasoft (especially to version 6X), but find it challenging. It provides users with a step-by-step Bonita migration process and highlights the common issues faced during the Bonita migration.
Bonita migration from 5X to 6X can be a tricky process, unless you are an advanced user or have an in-depth knowledge of the software.
In the below post, we have used two versions of Bonita:

  • A process bar file developed in Bonita Version 5X (5.10.2)
  • Bonita Subscription Edition – Performance, Version 6X (6.5.1)

Bonita Migration – Getting Started

The first step is to import the Bonita 5X bar file into the Bonita 6X studio. To achieve this, follow the steps outlined below:

  1. Open the Bonita 6X studio. Click on ‘Diagram’ and ‘Import’.
  2. Select ‘Bonita BAR 5.9/5.10’ and browse the location of the BAR file.
  3. Click on ‘Import’ to finish.

Technical Challenges

Some of the components that get affected during the Bonita migration are highlighted below.

Repository Issues
  • An important point to note here is that only the processes developed in Bonita versions 5.9/5.10 can be imported/migrated to Version 6X. Furthermore, the Bonita 6X studio does not recognize the Bonita 5X repository. Hence, Bonita 5X processes can be migrated to Bonita 6X only by importing the bar files. Once the import process is completed, a new repository needs to be created as outlined below.
  • The following steps have to be followed to create/connect to the Bonita repository:
    • In the Bonita studio, click on ‘Repository’ then ‘Team’ and then choose the option ‘Connect to the repository’.
    • A dialog box is displayed, enter the repository URL, username and password and click on the ‘Next’ button. A list of available repositories is displayed.
    • To create a new repository, select the option ‘Create a new repository’. A dialogue box appears, enter the repository name in the dialogue box and click on ‘OK’.
    • Select the appropriate repository and click on ‘Connect’.
    • It is important to note that Bonita version 5X repositories are not shown in the list of repositories.
Impact on Connectors
  • Upon migration, the connectors need to be checked thoroughly and users have to make sure that the code is tweaked according to the current Bonita version, which is 6X.
  • Custom connectors extend the Abstract Connector class. The method validateValues(), which is overridden in Bonita version 5X is not available in the Bonita version 6X and hence it has to be removed from the code post the migration, else it may display few errors.
  • The BAM (Business Activity Monitoring) KPIs are not migrated from 5X to 6X. Hence, they need to be re-configured in the new version.
Actor Mapping
  • The new actor mapping should be configured as the old mappings are not migrated during the migration process.
  • After creating new actor mappings, it is recommended to export the file and save in a local directory or an external repository.
Custom Data Types
  • Custom data types are not migrated during the migration process and will need to be re-created.
  • New organization should be created with groups, roles and user mapping configured accordingly.
Deprecated API Calls
  • There could be deprecated groovy scripts in the process due the API calls made in those scripts, which are not supported or deprecated in the newer versions.

Script Table

  • New scripts need to be defined in which appropriate API calls need to be made.
Rest APIs
  • Bonita exposes APIs to external applications. The APIs exposed in Bonita 5X are deprecated and hence after the migration these are not available. Users should look into this issue and update APIs accordingly. Here are a few examples:

APIs exposed in Bonita

Impact on User Interface
  • While executing a newly migrated process in the new Bonita version directly from the studio, users might face some UI issues, especially while displaying forms in the portal as shown below:

Bonita User Interface
Follow the steps outlined below to fix these issues.

  • Click anywhere in the pool, go to ‘Application’ tab.
  • Click on ‘Look ‘n’ feel’.

Bonita Look and Feel

  • Select ‘Apply a Look ‘n‘ feel’, the following dialogue box appears:

Select Web Template Screen

  • Select the ‘Default Application’ and then click on ‘Finish’.
  • Select ‘Yes’ when the following dialog box appears.

Dialogue Box Screen

  • Now ‘Save’ the changes made and ‘Run’ the process again from the Bonita studio. The new version look and feel is applied and the form is displayed as below:

Waiting Message Screen

Import Status Report

After a process is migrated in version 6X, while opening a diagram the status ‘Migration Ongoing’ is displayed next to the process name in the studio.

  • The ‘Migration Ongoing’ message indicates that few elements still require review, here’s a screenshot for reference:

Migration Ongoing Screen

  • The status column indicates, if the elements have been completely migrated or not.
  • An option is provided in Bonita 6X to generate the import status report. In order to generate the report, users have to click the drop down arrow as shown in the above diagram and select ‘Export as PDF’. Subsequently save the PDF file in a preferred location.
  • After the report is generated and reviewed, appropriate boxes should be checked and reviewed. After this process is completed, click on the ‘Exit Import Mode’, which will ensure successful completion of the process. When the process is opened next time, the ‘Migration Ongoing’ status is not displayed.


Migrating to the newer version of Bonita helps users to make use of the latest features that are available in this tool. The new features and tools of Bonita not only shorten the development process, but significantly reduce development time and improve application performance. Moreover, interesting features such as a rich user interface; the concept of business data modeling and replay a task/connector, when an error occurs makes it simpler to maintain workflows/processes. Bonita users will truly enjoy the experience working on the newer versions of Bonita. Here’s wishing you good luck for your Bonita migration.


Here’s an official link from Bonitasoft that contains an exhaustive documentation of the new features and concepts introduced in the Bonita version 6X.


Sujatha Ravichandran was a Software Engineer at Evoke Technologies. She is competent in core Java, web application development, Spring, Hibernate, HTML and CSS. She has an excellent grasp of Bonita BPM open source software and its functionality. Sujatha was part of multiple Bonita BPM projects at Evoke.
Please follow and share

Leave a comment