bonita-process-model

Contains the Bonita Process Domain Logic used by Studio and related tools.

Prerequisites

For building the code in this repository: Java JDK 17+

For using the libraries released: Java JDK 17+

How to build

With Eclipse

Different launch configurations exist in this repository. Build Bonita Process Model.launch can be used to compile and build the model java classes.

In your Eclipse IDE, right-click on the launch file, Run as -> Build Bonita Process Model

A console should appear and after a while, the build will be done. You can find the jar in the target folder of each bundle project.

With Maven Wrapper

./mvnw install

This will install all the Bonita Process Domain Logic artifacts and also a maven archetype process-reader-archetype.

How to use the Bonita Process Domain model in your own work

To make it easier for you, this project contains a maven archetype, which allows you to set up a project for reading a Bonita Business Process Model file.

The maven archetype : process-reader-archetype

This sets up a classic maven project that uses:

• org.bonitasoft.bpm.model for knowing the Bonita Process Domain Logic
• org.eclipse.emf.ecore to manipulate and load the model
• A sample .proc Business Process Model file

How to use the archetype

mvn archetype:generate \
    -DarchetypeGroupId=org.bonitasoft.archetypes \
    -DarchetypeArtifactId=process-reader-archetype \
    -DgroupId=org.company.bpm \
    -DartifactId=my-process-reader \
    -Dversion=0.0.1-SNAPSHOT \
    -Dpackage=org.company.bpm.reader \
    -DdisplayName="My Custom Process Reader" 

Archetype parameters

Parameter	Required	Default value	Description
-DarchetypeGroupId	true	org.bonitasoft.archetypes	Group id of the archetype
-DarchetypeArtifactId	true	process-reader-archetype	Artifact id of the archetype (must be fixed to the given value)
-DarchetypeVersion	false	Latest release version (9.0.0)	Version id of the archetype
-DgroupId	true		Group id of the project
-DartifactId	true		Artifact id of the project
-Dversion	true	suggested and asked interactively	Version of the project, suggested to use 0.0.1-SNAPSHOT
-Dpackage	false	suggested and asked interactively	Name of the root java package
-DdisplayName	false	suggested and asked interactively	Name of the project displayed
-Ddescription	false	Describe your project here	Description of the project
-Dwrapper	false	true	If set to true, project will setup a maven wrapper
-Djava-version	false	Same as in the main module *	Version of Java used by the project.
-Dbonita-process-model-version	false	Same as in the main module *	Version of the bonita-process-model used.
-Dmaven-clean-version	false	Same as in the main module *	Version of maven-clean-plugin module used by the project.
-Dmaven-resources-version	false	Same as in the main module *	Version of maven-resources-plugin module used by the project.
-Dmaven-compiler-version	false	Same as in the main module *	Version of maven-compiler-plugin module used by the project.
-Dmaven-surefire-version	false	Same as in the main module *	Version of maven-surefire-plugin module used by the project.
-Dmaven-jar-version	false	Same as in the main module *	Version of maven-jar-plugin module used by the project.
-Dmaven-install-version	false	Same as in the main module *	Version of maven-install-plugin module used by the project.
-Dmaven-deploy-version	false	Same as in the main module *	Version of maven-deploy-plugin module used by the project.

* These parameters are used to fix some versions. It is recommended not to use them and let the default values be used to ensure compatibility.

The versions of dependent modules are taken recursively by org.bonitasoft.bpm modules, so you can not choose them. This concerns EMF Core, EMF Common, EMF Ecore XMI, EMF Edit and maven-artifact modules.

Tutorial : displaying the content of a simple process

This tutorial will help you to read the content of a process file from the Bonita Studio and to display the content ( tasks, events, transitions... ). The code itself is already present in your newly project created.

The business process model file

In the resources folder of your newly created project, you should have a MyDiagram-1.0.proc file. This file is a Business Process Model File coming from Bonita Studio. It's a very simple process containing 4 tasks and a simple flow.

Launching the application with App.java

The App.java contain a main method which can be used to launch this application like a java application. It does the following things:

• Loading the process file: It will load the process file by using the ModelLoader class present in org.bonitasoft.bpm.model. This loading is very important : it will allow you to manipulate the content of the process itself through emf.
• Displaying the content loaded in html: The ModelDisplayer present in the project created can show you how to display in an html page the content of the process file. It can be used as a way to better understand how emf and the model logic work.

Other tools related to Bonita Process Domain models

Import from and export to BPMN 2.0

//TODO

P2 update site for integration with Eclipse RCP

You can also use the maven update site as a P2 repository / update site to use the provided features in your Eclipse RCP application. For the repository URL, you have to mention [mvn:org.bonitasoft.bpm:org.bonitasoft.bpm.eclipse-repository::zip] in your target platform (replace with the intended one). P2 will then ask Maven to search for the eclipse-repository maven artifact and will extract the P2 repository from it (provided your Maven configuration has access to Maven Central).

EMF Resources Knowledge

• EMF official eclipse documentation: https://eclipse.dev/emf/docs.html
• A tutorial describing the usage of Eclipse EMF: https://www.vogella.com/tutorials/EclipseEMF/article.html

How to release

This project uses the gitflow-maven-plugin for release management. Releases are created using the GitHub Actions workflow.

Branch Strategy

• develop: Main development branch for future releases
• support/A.B.x: Maintenance branches for older versions (e.g., support/8.0.x, support/8.1.x, support/9.0.x)
• master: Not used (removed, use support branches for maintenance)

Creating a Release

Releases are created via the GitHub Actions workflow Release

Workflow Parameters

Parameter	Description	Default	Example
version	Version to release (required for Tycho builds)	none	9.0.4
nextDevelopmentVersion	Next development version (leave empty to use versionDigitToIncrement policy)	empty	9.0.5-SNAPSHOT
versionDigitToIncrement	Version digit to increment in next development version	2 (patch)	0=major, 1=minor, 2=patch
previous-tag	Previous tag, used as starting point for release notes generation (required)	none	9.0.3
is-latest-release	Mark the GitHub Release as the latest release	false	true

Release Types

Patch Release (X.Y.Z) - Bug fixes and minor updates

• Set versionDigitToIncrement: 2 (default)
• Example: 9.0.3 → 9.0.4-SNAPSHOT
• Use for: Support branches, hotfixes

Minor Release (X.Y.0) - New features, backward compatible

• Set versionDigitToIncrement: 1
• Example: 9.0.3 → 9.1.0-SNAPSHOT
• Use for: Regular releases from develop

Major Release (X.0.0) - Breaking changes

• Set versionDigitToIncrement: 0
• Example: 9.0.3 → 10.0.0-SNAPSHOT
• Use for: Major version bumps

Major Release: bump the model version too

The process model version is the label of the latest release in bundles/org.bonitasoft.bpm.model/model/process.history, and ModelHistoryTest / VersionsSyncTest assert that it equals the major digit of the bundle version. The release plugin does not touch the history, and the release workflows skip the tests (-DskipTestProject, -DskipTests), so a mismatch only shows up on the next Build run.

So a major release must be followed by:

1. process.history: label the open (unlabelled) trailing release with the new major and a date, add a MigrationChange on UpgradeModelVersionAttributeMigration inside it, and append a new empty release.
2. .proc fixtures: re-version bonitaModelVersion, connector modelVersion and configuration:Configuration/@version.
3. Reader archetype: rename its MyDiagram-<version>.proc fixture, update AppTest and referenceOuput.txt.
4. Check with ./mvnw verify — ./mvnw test runs no test at all on the test fragments.

Use Eclipse (Edapt history editor) for step 1 and Bonita Studio (open and re-save the diagrams) for steps 2-3; editing the XMI by hand is only safe when the .ecore did not change. Full checklist in CLAUDE.md.

Release Process

When you run the workflow from any branch (develop or support/*), it runs three jobs in sequence:

1. release - runs gitflow:release:
   1. Update version to release version (removes -SNAPSHOT)
   2. Commit: "chore(release): Update versions for release"
   3. Create git tag (e.g., 9.0.4)
   4. Update version to next development version
   5. Commit: "chore(release): Update for next development version"
   6. Push commits and tags to GitHub
2. publish - checks out the release tag and deploys the artifacts to Maven Central (./mvnw deploy -Prelease)
3. github-release - creates the GitHub Release for the tag, with release notes generated from previous-tag to the new tag

The previous-tag input is checked at the start of the release job, so a missing or mistyped tag fails the run before anything is pushed.

If the github-release job fails for a transient reason (network, token), re-run only that job: the artifacts are already on Maven Central and must not be deployed again. A re-run reuses the same inputs, so it cannot fix a wrong input.

Only one release can run at a time per branch. A second run waits for the first one to finish, but only one run can wait: dispatching a third run cancels the one already waiting.

Note: The workflow does NOT create a release branch - it performs the release directly on the branch you selected.

Release Notes

Release notes are generated by GitHub from merged pull requests, using the configuration in .github/release.yml (picked up automatically by gh release create --generate-notes). Pull requests are grouped into categories by label. Pull requests labelled github_actions (set automatically on ci/* branches and on Dependabot GitHub Actions updates) or ignore-for-release-notes are excluded.

Cascade Merging for Support Branches

When releasing from a support branch, you should manually cascade merge the changes up to newer branches and develop.

Example: After doing a release from support/8.0.x, merge support/8.0.x into support/8.1.x, then merge support/8.1.x into support/9.0.x, and so on into develop.