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. It contains the source code of artifacts that made up a project, such as:

  • Diagrams of processes

    • Parameters

    • Configuration

    • Document

  • Business Data Model

  • BDM Access Controls

  • Application descriptors

  • UI Designer elements

    • Pages

    • Forms

    • Widgets

    • Layouts

    • Fragments

  • Organization

  • Profiles

  • Themes

  • Extensions

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 Git server that is used by the team collaborating on developing a process.
A shared project has typical code management features: synchronization, versioning.
Your workspace contains a local copy of the project, which is synchronized with the remote 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 (Enterprise only)

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 Bonita 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. A Project ID is derived from the given name. This ID can be changed but must respect the Maven artifactId naming conventions.

  4. You may set a specific version to the project.

  5. A Group ID must also be provided. A Group ID is a namespace that is used to uniquely identify your project from all other projects. Like for Project ID, it must follow the naming conventions.

  6. You may leave the target Runtime version to its default value. It can be adjusted if you want to target specific runtime version (eg: Using a Bonita Studio 2023.1-u4 to develop a project deployed on 2023.1-u1 runtime)

  7. An optional description can be given

  8. Click Create .

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

A Bonita project is Maven multi-module project. The Project ID is used to derive all submodules artifactId. It is not supported to manually change the groupId, artifactId and version. It is mandatory to use the Edit project information…​ dialog from Bonita Studio.

Export/Import a project

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

  1. Click on File > Export project

  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

Prerequisites

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 the GIT entry in the coolbar.

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>).

troubleshooting-icon Troubleshooting

Git

  • 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. https://user@dev.azure.com/organization/repository/_git/repository). Use SSH URL instead (e.g. git@ssh.dev.azure.com:v3/user/organization/repository)/

  • 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 "your_email@example.com".

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.