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

How about downloading a newer, supported version?

Workspaces and projects

Organize and share your Bonita project using workspaces and projects in order to ease developers team collaboration.

Workspaces and projects

A workspace is a directory where Bonita Studio stores files such as Studio configuration settings (shared by all projects in the workspace) and projects folders. When you install Bonita Studio, a default workspace is created automatically: the folder is named workspace and is located in your Studio installation folder.

A project is a directory within your workspace.
You can use local projects to organize your work efficiently, for example by separating processes that do not interact.

A team project is a shared project on a Subversion (SVN) or Git server that is used by the team collaborating on developing a process.
A shared project has typical code management features: locks (SVN only), synchronization, versioning.
Your workspace contains a local copy of the project, which is synchronized with the remote Subversion or Git server.
Note that the values of the Local process configurations (such as parameters) will not be synchronized on the remote repository, to allow each Studio to have its own configuration. You can use another environment for shared configurations (Qualification, Production or custom environments).

Switch workspace

The default workspace is studio_install_directory/workspace.

To use a different workspace:

  1. Go to the File menu and choose Switch workspace…​.

  2. A pop up window shows the path of the workspace you are currently using.

  3. In the pop up window, specify the path of the workspace you want to use. If the selected destination does not exist, you are asked whether you want to create a new workspace.

  4. Click OK.

  5. The workspace switch is applied the next time Bonita Studio starts. Click OK in the pop up window to restart the studio, or Cancel to continue using the current workspace.

Create a project

You can create a project in your workspace.
The project is created in your current workspace.

To create a project:

  1. Go to the File menu, choose New project…​.

  2. Specify a name for the new project.

  3. Click OK .

A new project is created. Only one project can be active at a time.

Export/Import a project

You can export all the content from a project for exchange or backup purposes:

  1. Click on File > Export…​

  2. Choose a location on your local drive to store the archive and click on Finish.

The exported archive can then be shared with other studios of the same version or newer.

To import a BOS archive:

Starting with version 2021.2, Java versions lower than Java 11 are no longer supported.
As a result, some of the dependencies in the projects imported from previous Bonita Studio versions may not be compatible with Java 11 (for example, an old dependency may contain some packages that have been moved into the JDK in Java 11, which could lead to issues with modules as the same package might be loaded twice).
This typically leads to the following error: The package XXX is accessible from more than one module: <unnamed>, YYY

Please double check all your dependencies in the project exported from a previous Bonita Studio version and make sure they are compatible with Java 11 before importing it.

  1. Click on File > Import > BOS Archive…​

  2. Choose the location of the archive on your local drive

  3. Choose if you want to import the content in an existing project or create a new one.

  4. Handle conflicting files if any

  5. Handle dependencies conflicts if any

  6. Click on Import

If your not using Git, you can retrieve the whole content of another studio workspace by exporting all its projects and importing them into another studio.

Switch project

Before you change to a different project, make sure you have saved your work.

To switch the current project, follow these steps:

  1. In the File menu, choose Switch project…​.

  2. The list of the available projects is displayed. These are the local and shared projects in your current workspace.

  3. Select the project to switch to, and click OK. Switching project restart the Bonita Runtime so it can take a few seconds.

  4. A confirmation message is displayed when you are working with the new project.

If the list does not contain the name of the project you want to use, check that you are using the correct workspace, and if necessary, switch workspace.

Use a shared project



Git integration in Studio

Bonita Studio Git integration is based on the EGit Eclipse plugin.

Git commands available in the studio interface:

  • Share with Git
    This action connects the current project to Git and shares it on a remote. To configure the remote, see the following Egit user guide or the Share on GitHub howto.

  • Clone
    Create a new Studio project from an existing Git repository (that must contain a proper Bonita project). If the remote project version is lower than the studio, a migration will be applied on the cloned project. Be careful before pushing a migrated project back to the remote: all contributors will have to use the proper studio version.

If you used Bonita on Git before Bonita 7.7.0, you might want to clone it from the studio.
Be careful though: we cannot guarantee that cloning a Git repository not created with Bonita Studio will work properly.
However, to do so, first check that your project on GitHub is "Bonita compliant":

 * The Git repository content must includes a Bonita project (and not a Bonita workspace)
 * The .project file must be present
 * It is highly recommended to use the .gitignore file generated by Bonita when you share a Bonita project from the studio.

Still, the best way to proceed is to export the project from the older version of the studio (as a .bos file) and import it in the new studio, and then share this project on Git, although with this procedure, the history of revisions will be lost.

  • Commit…​
    Shortcut action to add, commit and push the local changes.

  • Push to Upstream
    Send the local committed changes to the configured upstream remote repository. You should make a pull before pushing.

  • Fetch from Upstream
    Download new data from the upstream remote repository. It doesn’t integrate any of this new data into your working files. Fetch is great for getting a fresh view on all the things that happened in a remote repository.

  • Push branch…​
    Send the local committed changes to a specific branch on the remote repository. If the push fails, you may need to use make force push with the command line tool.

  • Pull
    Fetch and try to integrate the remote changes of the current branch. This operation can put your repository in conflicting state. Use the Git staging view and provided merge tool to resolve the conflicts. You can abort the merge with a hard reset with the command line tool or the Reset... action.

  • Switch branch
    Change current branch, checkout a new branch from remote or create a new branch.

  • Merge
    Merge the content of a branch into current branch. Reference article

  • Reset
    Reset the content of the working tree to the head reference (latest commit).

  • Rebase…​
    Like a merge, you can retrieve the content of another using a rebase. It replay all commits of a selected branch into the current branch. Reference article

  • Git staging view
    This view display the current status of your repository. From this view you can stage/unstage your changes, commit and even commit and push. You can access to the compare editor using the contextual menu. More information available in EGit user guide.

  • History view
    This view display the commit history of the repository. More information available in EGit user guide.

  • Status This gives you connection information with the remote as well as the current status (ahead or behind) compared to the remote. This information is also available at the top of Bonita Studio window, as well as at the top of the Git Staging view.

Those commands can be found in Team > Git menu.

Branches can be merged/rebased into each others if and only if branches are in the same Bonita version. Else, migration might be skipped.

Conflict management

The use of Git often lead to conflicts when contributions are merged. There is different ways to manage conflicts, with a diff tool, in a text editor…​
Bonita Studio integrates the default merge tool of EGit. Here are some hints on how to resolve conflicts using EGit: Manage conflicts using EGit.

Advanced Git commands

Git workflow offers a lot of other features that are not directly integrated in Bonita Studio. You can still use them using the command line interface (available here). To retrieve the location of your project on your filesystem do a right click on the project name in the project explorer and select Show in system explorer (default location of your project would be: <bonita_studio_install_dir>/workspace/<name_of_the_project>).

Subversion (SVN)

SVN integration has been deprecated. Use the Git integration instead.

A shared project is a repository on an SVN server. It can be accessed by members of the team working on a process definition.
It is protected by username and password. Only directories in the SVN 'trunk' can be used as Bonita repositories.
The repository created remotely is then copied to your default local workspace and synchronized.

A shared project contains the artifacts developed in Bonita Studio and the UI Designer. For the UI Designer artifacts, there is no locking, merging, or conflict management.


  • A central SVN server accessible by the process designers, accessible by URL, and protected by login and password.

  • The same version of Bonita must be used by all users of the shared project.

Shared a project

There are two stages to creating a repository: connect to the SVN server, then specify the name of the new repository. Follow these steps:

  1. In the menu Team > SVN.

  2. Click on Connect to a repository.

  3. In the Create a new connection window, enter the URL, username, and password in the appropriate fields.

  4. Click Next to connect to the remote SVN server.

  5. From time to time, depending on your system and network security setup, you may be asked to confirm security credentials.

  6. A popup displays a list of the existing Bonita repositories available on the SVN server.

  7. Click on the button Create a new Bonita project.

  8. In the window, Project name, give the project a name e.g "my_new_project".

  9. Click on OK.

The new project is created locally and copied remotely to the SVN server. You can configure synchronization for this new shared project.

Connect to a shared project

To connect to a shared repository, follow these steps:

  1. In the menu Team > SVN.

  2. Click on Connect to a repository.

  3. In the Create a new connection window, enter the URL, username, and password in the appropriate fields.

  4. Click on Next to connect to the remote SVN server.

  5. From time to time, depending on your system and network security setup, you may be asked to confirm security credentials.

  6. A popup displays a list of the existing Bonita repositories available on the SVN server.

  7. Select the name of the project, and click Connect.

  8. A message is displayed, showing that you are connected to the shared project.

  9. Click on OK.

The first time you connect to a repository, you might get a security warning.
Configure security for the connection according to your organization’s security policy.

Synchronize a shared project

Synchronizing a shared project means merging the changes you have made in your local copy into the central repository on the server, and updating your local copy with the result.
There are three modes for synchronizing:

  • Recommended: Use manual synchronization for all repositories: With this mode, no automatic synchronization is done in either direction. This is the default behavior. You launch synchronization manually, by going to the Team > SVN menu then Commit artifacts. There is also a keyboard shortcut: Ctrl+Alt+C.

  • Use automatic synchronization for all repositories: With this mode, every time you make a change, it is saved in both your local copy and the central repository. Changes made to the central repository are sent immediately to your local copy.
    You can only use this mode if you have a continuous network connection to the system hosting the SVN server. There is a significant network performance cost for using automatic synchronization. This option is not recommended.

  • Define synchronization mode project by project: With this mode, you define whether synchronization is manual or automatic for each project.

Manage locks on shared resources

This information applies to artifacts created in Bonita Studio but not those created in the UI Designer.

Bonita Studio automatically locks an artifact (process or shared resource) when you open it for editing. You can also lock an artifact manually.
If you try to open an artifact that is locked by another user, a popup tells you that the artifact is logged and gives the SVN username of the person who owns the lock.
You can choose to open the artifact in read-only mode, which means you cannot make any changes.
It is also possible to unlock a locked artifact and lock it yourself, but this is not generally recommended except as a last resort if the owner of the lock cannot be contacted to release the lock.

You can choose to open an artifact in read-only mode, even if it is not locked by another user. If an artifact you are viewing in read-only mode is locked, there is a lock icon in the name tab at the top of the whiteboard.

To manually lock or unlock an artifact:

  1. Go to the Repository menu, and choose Team, then Manage locks.

  2. A popup displays the list of artifacts.

  3. Select the artifact to lock or unlock, and then click the Lock or Unlock button.

  4. Click OK.

To check the lock status of an artifact, go to the Diagram menu and choose Open, or click Open in the coolbar.
In the popup, artifacts that you have locked are marked with a green padlock, and artifacts that another user has locked are marked with a red padlock and the user’s SVN username.
From the popup, you can:

  • Open a process that you have locked (marked with a green padlock) or that is not locked (no padlock).

  • Open a process in read-only mode. You can do this for any process, but it is most useful for a process that is locked by another user (red padlock).

  • Open a locked process (red padlock). You can open a locked process in read-only mode. You cannot open a locked process read-write.

Avoiding conflicts

A conflict occurs when two or more users update the same process in a project and the updates are not compatible.
If you are using a shared project, Bonita Studio automatically locks a Studio artifact when a user opens it for edit. (Note: UI Designer artifacts are not locked.)
This means that only one user at a time can update the artifact, avoiding the possibility of conflicts. The only risk of conflicts is if a user takes over a lock from another user who has not committed their changes.
For this reason, you are not recommended unlocking artifacts that are locked by another user.

It is also a good practice to commit your changes regularly, to keep your local working copy synchronized with the central repository.
To commit your changes, go to the Team > SVN menu, and then choose Commit artifacts.
When you commit your changes, you have the option to release the lock so that another user can edit the artifact. By default, your lock is maintained.
If you want to release the lock, uncheck the Keep locks box in the Commit dialog.

Versioning and history

If you are using a shared repository, all modifications to an artifact are recorded by the SVN server.

To view the history for an artifact:

  1. Go to the Team > SVN > History.

  2. In the history list popup, select the artifact in the left-hand column.

  3. The revision history for the selected artifact is displayed in the right-hand column. This shows all the changes that have been made, and the author of each change.

To revert to an older version, click on that version in the revision history, then click on Revert to this version in the popup.
The selected version will be restored.

Restore points

A restore point is a marker in a repository that you can use to restore your project back to an earlier state.
The difference between a restore point and a version in the revision history is that a restore point applies to the whole project but a version applies to a single artifact.

To create a restore point:

  1. Go to the Team > SVN then Manage restore points.

  2. Select Create a restore point then click Next.

  3. Enter a description for the restore point, then click Create. The restore point is created.

To restore an older point:

  1. Go to the Team > SVN, then Manage restore points.

  2. Select Restore to an older point then click Next.

  3. Select the restore point you want to restore, then click Restore. The project reverts to the restore point.

troubleshooting-icon Troubleshooting


  • I see this type of message in the Studio log, but when I open the URL in my browser, it works fine: !MESSAGE An exception occurred during push on URI http://your_remote_git_repository/repository/my_bonita_repo.git: http://your_remote_git_repository/repository/my_bonita_repo.git: 503 Service Unavailable. You probably connect to the internet through a Proxy and you need to configure Proxy Settings in the Studio preferences.

  • My diagram has many validation issues after a clone / a switch branch operation: Keep in mind that Bonita artifacts (Business Data Model, Organization, Profiles, Applications, Pages …​) are not redeployed when you perform a clone or a switch branch operation. So, if you switch from a branch A to a branch B, you may need for example to deploy manually your BDM to ensure that all the business objects specific to the branch B are available.

  • My git history view is empty: The history view is based on the active editor or the current selection (in Eclipse, a selection is a file selected in a package explorer). Sometimes you can manage to open the history view without having any active editor and nothing selected (which is often the case in Bonita because we only provide a package explorer in the REST API extensions editor) -> the history view does not display anything. Just open a diagram for example and then re-open your history view.

  • Cloning a repository hosted on Azure DevOps When authentication to azure dev ops git repository uses SSO, cloning using https and Microsoft dedicated eclipse plugin is not supported (e.g. Use SSH URL instead (e.g.

  • I try to use git with HTTPS, but I have authentication issues (not authorized) This might happen if you have enabled the two factor authentication on your GitHub account. You must use an access token to be able to use HTTPS with the two factor authentication activated. Once the token is created, use it instead of your password. An other solution is to use ssh.

  • I have invalid privatekey issues when I try to use Git with ssh on macOs: Since the macOs mojave update, the ssh-keygen default export format has changed. The new format isn’t compatible with all eclipse versions. Use the following command to force ssh-keygen to export the private key as PEM format if you face this issue: ssh-keygen -m PEM -t rsa -b 4096 -C "".

My Studio crashed and I’ve lost my projects in my workspace

Since 2021.2-u1

You can enabled the workspace recovery mode that will synchronize the file system and the Studio workspace.
Open the BonitaStudio*.ini file matching the executable name (in the bonita installation folder, next to the workspace folder) and set the value of the system property workspace.recovery.mode to true. Then, restart the Studio.
In the Studio logs, you should see that the recovery mode is enabled and the import operation of the missing projects into the workspace. Once the recovery operation done, you may want to disable the workspace recovery mode by resetting the property value to false in the .ini file.