This documentation is about a version that is out of support, here is the latest documentation version.

How about downloading a newer, supported version?

Project phases

This page describes the six phases strongly recommended to create an optimized and secured process-based automation project using Bonita.

Project phases

Project discovery and design

Project discovery

Discovering the project accounts for the finding of the first process within a company or a department, eligible to automation, that will benefit from the full power of Bonita while providing the biggest value to the end-users once in production. This process must be core to the business of the company or department.
Eventually, this one process may be rendered by several BPMN processes, all of them handling different aspects of the business process identified.

Objectives of the project

Once the value has been evaluated, it is described in objectives to reach with this automation project.
The more measurable the objectives, the better the performance indicators to monitor how close the project is from the objectives.
Objectives can be qualitative or quantitative, and should cover the expected lifecycle of the process.
For example, if you want to create an automated process to replace an existing process that uses paper forms, you could define objectives for how long it takes to fill out a form in the initial roll-out period, and after 6 months when users have become familiar with the new system. You could also define an objective for the savings achieved by no longer storing paper documents, or quality objectives that the process must meet before deployment.
Once the objectives are set, the team can create key performance indicators to measure how the process execution will bring operations closer to the objectives.

Scope of the project

Defining the automation project scope means defining how it will be owned (governance), created, and maintained (project team); who will use it (users) and how it will be used (usage); the information it will handle, the level of security needed, and the connections to external systems it will require.

  • Governance: The people who will be accountable of the quality of the overall project, but also of the quality of the underlying processes. Those can be different teams.

  • Project team: The people who contribute coding skills, business skills, project management skills, and other needed skills (database, testing, security…​) to the project

  • Users: The people who will benefit from the project, both at management and actual end-users levels.

  • Usage: The times, frequency and periodicity of use, the number of simultaneous accesses to plan for for the main use-cases, but also- for the exceptional use-cases

  • Information: The business domain the project encompasses, where the data will be stored, what amount of data is expected, what flow data will follow in the company’s information systems

  • Security: The kind of risks and controls needed for people using the application

  • Connections: The needs to exchange information through connections to external systems (databases, content management systems, email server, REST APIs), and the feasability of such exchanges through Java or REST APIs

Type of the project

Early on, the project team needs to figure out what type of an automation project they will create:

  • RPA or not RPA: when there are legacy systems to connect to, that are not reachable through Java or REST APIs, there is a need to insert small robots that will act as humans to copy/paste information from one system to the other or perform other low-value tasks along the process. The project then enters the Robotic Process Automation (RPA) world, which Bonita supports with its partnership with UiPath.

  • Web application or no web application: if there are not many users in the process, like the automated execution of a backup recovery plan in a data center, the automation project may not need a web application. Most of the time, it does.

There are three main kinds of applications to choose from at an early stage, based on the type of interaction they create:

  • Tasklist applications: all processes are mixed, users do tasks by priority or through a certain filter. Bonita Applications deliver such a user experience. This application can be partially customized.

  • Data-centered applications: the processes manage the lifecycle of business objects instances, like requests. Users need a generic view of all requests at any time, but also to act on specific requests at a given time, and to do so, they need to filter the request list and t o perform actions related to the requests to make their status evolve. These are business-specific and need to be developed as Living Applications.

  • Case Management applications: the process is not as structured as in full BPM; users are considered as domain experts who can decide whether to do some tasks or if this is not appropriate, the best time to do a task, or to create new tasks during the lifetime of a process instance (case). The case is mainly made of the manipulation of a complex business object (the request, for example), created when the case starts, edited during the case lifetime, and stored after the case ends. Here again, Bonita provides an Adaptive Case Management application as an example to customize.

When this choice is done, the type of the project is clearly defined.

Based on the previous information collected, the complexity of the project can be estimated, and a budget can be defined, followed by, hopefully, the right resources allocated to make it happen.

Project design

Process details

Using Agile methods like Event Storming, or any kind of workshops involving business users, professional developers, and a facilitator (internal or externally hired for the workshops), the processes are specified in all their details in a collective approach.
The users know how they work today and what they could need; the developers know what is technically feasible, what is very costly, the facilitator knows what changes to expect from process automation, and so a negotiation can happen in this very first approach to avoid later frustrations and conflicts.

When the process is specified from the workshops, it is ready to be implemented in its BPMN format in Bonita.

User Interfaces

Using Agile methods like Design Studio, or any kind of workshops involving business users, professional developers, a user experience designer, and a facilitator, the User Interfaces are created in a collective approach, in the form of mockups.
Here again, the negotiation between the need and how it can be efficiently rendered is done at an early stage.

When the UI mockups are precise enough from the workshops, they are ready to be implemented in Bonita:

  • For forms: from the pool Execution properties (instantiation form and case overview), and human tasks (task forms)

  • For application pages: directly from the UI Designer

Business Data Model

Through the process and user interfaces workshops, the business data model is identified and can be specified too. It is ready to be implemented in Bonita.

Configuration - Installation

While the project team works on the content of the project, the development team needs to set up their development environment, to easily version and share the project, as well as automate the project builds.
For Subscription editions users, this is also the time to configure 3.6@bcd::index.adoc[Bonita Continuous Delivery].

Moreover, if the project will be deployed on premises, the infrastructure team works on the installation of the non-production and production environments.
There are many options for how Bonita can be installed: see the Installation overview for details.

Implementation - Test I: Make sure the process does what it should

Processes, Data, People

Using Bonita Studio, anyone trained to the Business Process Model and Notation as a citizen developer or professional developer can quickly implement BPMN versions of the processes, Business Data Model, specify the documents handled by the processes, as well as create business variables in the processes.

It is also very easy to create the actors that will start the processes and execute each human task, create a sandbox organization in Bonita Studio, and then configure the mapping between each actor and the organization entities for testing purposes.
If the actor is linked to the process execution (like the same person who executed the previous task), an actor filter must be created as an extension by the professional developers and be made available to the project.

Then, for each process instantiation and human task, a contract must be defined, that state to each form what a task needs to be executed, or what the process needs to start. The information needed can be a new information to create, or an existing information to edit.
This contract will be evaluated when the form presents its output to the process.

As for the user interfaces per se, at this stage, Bonita provides auto-generated forms that allow the early testing of the process execution.


For now, connectors responses must be mocked by scripts made available by the professional developers to the project as extensions.
The exception to that could be the notifications (when a task is ready, when a task is executed), rendered in Bonita with an email connector. Configuring the email connectors could help in gathering feedback in this first implementation phase.


  • Process start and end. Most business processes have a single start and a single end, but it is possible to have multiple starts and ends.

  • Parallel gateways. If there are activities that happen in parallel, use symmetric gates to map out the beginning and end of the parallel phases of the process.

  • Step details. Make sure each step is the correct type, and has a descriptive name.

  • Transition details. Make sure all transitions have a descriptive label. Make sure there is always a default path at each branch in the process. If the process contains a loop on a step, make sure there is a maximum number of iterations defined.

  • Exception handling. Plan for how errors and unexpected events will be handled. Consider whether it is necessary to stop the case or process, or whether the case can take an alternate path. Decide whether to use event sub-processes.

  • Actors. Define the actor for each step, applying an actor filter where necessary.

  • Process maintainability. Add annotations to explain the process. Make sure all elements have descriptive labels. Generate the process documentation and check it.


Bonita Studio includes an environment for testing a process locally, before deployment: when clicking Run, the embedded Runtime executes the process instances and displays the User Application by default. The choice of the default application to open can be configured.
All along this first implementation phase, feedback must be taken from the process owner and business users, through Agile sprint demonstrations as well as usability testing sessions.

Implementation - Test II: Work on the user experience

Process forms

In Bonita Studio, in the pools Execution properties (instantiation form and case overview), and in each human tasks Execution properties (task forms), you will find a tool that creates the first version of the forms, based on the contracts. These first versions can be customized later on.

Application pages

Besides the forms, and following the findings of the UI workshops, application pages may be needed to display generic information about business data. They can also replace a form when all the user needs to do is clicking on a Approve or Reject button.+ If the project is a Case Management project, you can customize the provided project.
The create-or-modify-a-page.adoc [creation of pages] is done directly in the UI Designer embedded in Bonita Studio.

From the UI Designer, you can also define the layout of the application, although Bonita provides an efficient default Layout.
A theme can also be defined to match the graphical design charter of the company. This can be done my customizing one of Bonita’s provided themes.
The theme needs some coding (CSS, html) skills to be created or customized. Once developed in the developer’s favorite IDE, it needs to be made available to the project as an extension.

Profiles and applications

From the studio, the profiles are created to grant access to the future applications, mapping each profile with organization entities.
Defining the application then comes down to binding together project elements: a profile, some pages, a layout, and a theme.
The application descriptor also allows for the creation of a name, a URL token, the application two-level navigation and the designation of the home page.
The link between an application and the processes that run in the background is created by the BPM API called by the clickable elements contained in the pages. There is no need to formally declare such a link.

You can either create an application from scratch, or customize a Bonita application.

In this latter case, choose well, as each application is devoted to a special business need:

  • Bonita Super Administrator application: bootstrap Bonita after the deployment in a non-production or production environment

  • Bonita Administrator application: monitor the execution of the process instances and troubleshoot

  • Bonita User Application: Start processes and execute tasks

  • Bonita Application Directory application: display all applications the logged user can access

  • Adaptive Case Management example for Case Management. Note that this example is only available for the Enterprise edition.

To customize an application to your needs:

  1. From Bonita Studio’s Welcome page, in the "Resources" tile, download the application that suits your needs. In the studio "Project explorer" pane, you will find all resources of the application: descriptor, layout, theme, custom widgets, as well as some pages. Our pages have been developed with different frameworks over time.

    • Pages developed with the UI Designer appear in the Project explorer, they can be edited in the UI Designer

    • Pages developed with AngularJS are embedded in the Development Suite Tomcat and can be found in the Resources page of the Bonita Administrator Application. Those pages are angularJS pages that have been "wrapped" from to be used as custom pages. They cannot be edited in the UI Designer.

    • Pages developed with React are embedded in the Development Suite Tomcat and can be found in the Resources page of the Bonita Administrator Application. Those pages cannot be edited in the UI Designer but they can be modified using an IDE (Integrated Development Environment) if needed.

  2. Duplicate the application descriptor and rename your copy

  3. Delete the pages you do not need, add the pages you need, keep the pages that fit the target use

  4. To customize the pages created with the UI Designer:

    1. From the project explorer pane, double-click on the page to open it in the UI Designer

    2. Make it yours

    3. We recommend that you save it under another name, in case you need the original version at some point

Note: While the Bonita Applications are supported by Bonitasoft in their original versions, any customization of yours cannot be supported, as Bonitasoft cannot garantee the content of your custom development.
Similarly, the Adaptive Case Management example, which can only be used after it is customized, is not supported. However, our team of Professional Services consultants can assist you in the customization phase (Subscription editions only). You can contact them through the Customer Services Center.

To know about the pages that can be customized, go to the create a page documentation page.

Connectors - final implementation

To use a connector, it must first be declared as a dependency of the project. This is done from the Studio Extensions page. The connector can be found in Bonita Marketplace or can be made available the professional developers of the project team.
In this phase, attach the real connectors implementation to the relevant steps.
Note that it can be more efficient to split steps with both user activity and connector activity into two steps, a human task for the user and a system task for the connector.


  1. Test each connector independently using the connector wizard Test button.

  2. You can validate a process definition in Bonita Studio, in the Details panel, Validation status tab. The validation status indicates any errors or omissions in the definition. Correct any errors flagged in validation before testing the process

  3. Then, test each process individually (run the process by clicking Run). You need to configure the process before testing it locally.

  4. Test the application. Make sure the user interfaces display the right information, and gather the right information. Run usability testing sessions with end-users.

From development to production

When local testing is complete, the processes are ready to be deployed and the application is ready to be put into user acceptance testing, staging, and then production environments.
You need to configure each process for deployment before deploying into a new environment.
Continuous Delivery can be achieved thanks to Bonita Continuous Delivery (Subscription editions only).

Go to production

Complete organization

Before you can run a process in production, you need to define your organization with entries for all process users, groups, and roles. You also need to map the process actors to the real people who will carry out process steps. This is most of the time achieved thanks to an LDAP, and system administrators will then use Bonita LDAP synchronizer.


REST API extensions, static and dynamic API security rules, BDM access control, actor filters, actor mapping, profiles need to be specified and/or double-checked at that time, to make sure that accesses are given to the right people for the right data.


This is also the time to translate the applications into all languages needed by the end-users.

Runtime installation

In order to make Bonita applications available to end users you need to set up a Bonita Runtime. If you have to expose Bonita Runtime or a Bonita-developed application publicly, you should set up a reverse proxy.

Monitoring, Troubleshooting, Maintenance, and Evolution

After deployment, you can monitor usage and collect key performance indicators, to assess how well the process is meeting the objectives that have been defined at the birth of the project. It is also possible to make small and temporary evolutions to the processes and applications, but we strongly recommend that all long-term evolutions are made in Bonita Studio to create a new version of the project, and then deployed and tested until it is pushed to production.