DEV Community: Bonitasoft

Bonita online documentation needs some Hacktoberfest 2022 love!

Thomas Bouffard — Wed, 05 Oct 2022 08:01:14 +0000

What?

Bonitasoft is taking part in Hacktoberfest, a month-long celebration of open source software, where developers are encouraged to - and rewarded for - contributing to open source projects like Bonita.

In this friendly, worldwide event, maintainers are invited to guide would-be contributors towards issues that will help move their projects forward, and contributors get the opportunity to give back - to projects they like, and to others they've just discovered.

This year, we propose work on the design of the online Bonita documentation web site 🔥.

For example, there is an opportunity to improve the light and dark themes 🎨, improve the look and feel for mobile, and much more 😍.

Who?

This project is open to everyone and no contribution is too small — bug fixes and documentation updates are valid ways of participating ✨.

How?

It's easy! Register on Hacktoberfest with your GitHub account, search for issues to contribute, and send at least 4 pull requests ... After the 4th validated PR, you win the Hacktoberfest 2022 👕 or a 🌲 is planted in your name (first 40,000 participants, so get in there early!).

To contribute to the design (a.k.a bonita-documentation-theme) of the Bonita documentation site:

Check the opened issues available for Hacktoberfest.
Find one that you are interested in and which is not already assigned to someone.
Post a comment to mention you are willing to work on this topic. We will acknowledge and will assign it to you to inform the world!
Work on a Pull Request. Ask any question if you are blocked or you need more details to complete your task.
Submit your Pull Request. We will review it quickly and will work with you to ensure it is merged and visible on the documentation site

We are looking forward to your contributions 👋!

The story of Bonita Documentation! The need for a new documentation site

Thomas Bouffard — Wed, 08 Dec 2021 11:27:00 +0000

Have you ever had a question, an issue, a need to know something about Bonita? If yes, you’ve probably visited the friendly Bonita Documentation!

In March 2021, we launched the new Bonita Documentation site, which offers fixes and improvements. If you want more details about the new site content, here’s the site go live announcement.

We want to share with you the story of the Bonita documentation evolution in a series to explain how and why the Bonitasoft team decided to make this latest change.

In our previous article, we described the fascinating history of the Bonita Documentation site 2016 version.
Here we’ll show some of the issues we have faced over time and the solution we have been looking for to resolve them.

Issues with Bonita Documentation 2016

The Bonita Documentation 2016 version was designed to manage documentation for Bonita Studio and Bonita Runtime only. By 2020, it was unable to support new needs, and we faced major issues in the user experience, maintenance, and operations that couldn’t be solved easily.

User eXperience

Improvements made with the 2016 version of the Bonita documentation mainly focused on the content and how to update it, but not so much on the User eXperience (UX).

The site didn’t have a useful bookmark system. There weren’t real anchors in its pages, so it was hard to bookmark a specific section and to navigate between related content on pages and sections.

The embedded search feature was also limited due to the lack of proper anchors. Clicking on a search result didn't send the user to the paragraph that matched the search request, but to the top of the page instead. There was then no other choice but to scroll in the page looking for the expected paragraph.

“Recycling” by Griszka Niewiadomski

SEO was also an issue. Some pages of very old documentation versions were better indexed than their related page in the latest version, so search engines sometimes led the reader to outdated content. Navigation to new content required extra clicks and extra searches in the documentation site.

One of the impacts of these issues was that readers could too easily miss the information they were searching for. This was not the best user experience and we wanted to do better.

Maintenance

The Bonita Documentation 2016 version involved custom Python scripts to aggregate document contents coming from various sources, using one repository per documentation component and a branch per version.

This documentation content structure worked perfectly well, as

branches were useful for for updates backport/cherry-pick/merge
repositories were useful for content segregation, access management, product and documentation lifecycle alignments.

Each branch in each repository was responsible for generating its documentation part; the aggregation scripts were in charge of assembling everything and adding the final styles.

Initially this worked well, as there was only a single documentation component (the Bonita platform) and only a few versions.

Over time though, the Bonita portfolio has grown and now contains more products (including Bonita Continuous Delivery, and Bonita Cloud), so more components and more versions were added to the documentation.

Duplications of repositories began to appear and we had to make changes in multiple places. Inevitably more and more problems arose. For example:

At one time, it was possible to generate a PDF file for a given version of a component. This function was abandoned as it did not work properly, but was still present in all branches.
The build process of all versions was full of unused tools and dependencies. This slowed down the build.
We accepted changes in Markdown with custom syntax (for instance, to manage information and warning blocks), native HTML tags, and Font Awesome icons. But minor changes then had to be replicated to all repositories.

As noted, the Bonita Documentation 2016 was complex and hard to maintain. It used an aged technical stack and it was especially hard to build. Developers who may have been able to implement changes were not very encouraged to do so!

We saw very few technical updates, fewer and fewer bug fixes, and the user experience issues remained.

Operations

The Bonita Documentation 2016 version had continuous deployment and preview environments. This was perfect for day-to-day work; changing the documentation content was straightforward. The changes were propagated from staging to production transparently.

“Pull Request Flow” taken from the Agile Grenoble 2017 presentation “Fluidifier la production de la documentation”

But we also faced operational pains.

Adding a new component version (for instance, when preparing a new Bonita beta version) involved multiple actors and synchronization.

The configuration to actually manage the version was spread across several locations.
Synchronization was done using tickets, and direct conversations.

This lack of ability to self-service updates slowed down the process a lot and generated frustration.

The documentation site build, and deployment to the preview and production environments, were all managed with internally-operated Continuous Integration servers (Jenkins).

Internally-operated meant dealing with Jenkins and server updates. As it involved a large amount of custom scripts and Jenkins jobs, this also meant maintenance to follow the Jenkins evolutions.

The pre-production and production environments were composed of front-end and search (Solr) servers, also operated internally. This was another area for regular maintenance costs.

As we didn’t rely on a CDN, the latency could be high depending on the location a user was browsing the documentation from.

The previous Drupal-based documentation

Prior to the Bonita Documentation 2016 version, Bonita documentation (for Bonita BPM v6.0 to v7.2) was managed on Drupal.

This content had to stay online for a transition period, up until the versions reached end-of-life. As often happens with legacy assets, it was still available years later.

There were no plans for decommissioning or migrating, and it contained very old content which hadn’t been updated for a while.

It had its own dedicated infrastructure still live more than 4 years after the rollout of the Bonita Documentation site 2016 version. The operations team had to deal with security (stack hard to update) and user experience concerns (no changes to the site while browsers have evolved, resulting in some broken features).

Photo by Thiébaud Faix on Unsplash

The New Solution: What We Dreamt About

All the issues explained above began to have more and more impact on Bonita documentation users. We really wanted to get in there and improve the site!

We first prototyped a new solution based on Jekyll for HTML generation, keeping most of the existing Markdown content and the Python aggregator. We also investigated moving the search solution from Solr to ElasticSearch.

While having a true static site was a great improvement, a lot of issues remained unresolved.

The prototype only addressed a part of the user experience issues; maintenance and the operations sides still presented issues. The site still included a lot of custom code in particular for the content aggregation.

So this approach was not a game changer, although it was a way to do basically the same thing better. But ultimately it didn’t provide enough improvements.

So we decided to change our direction, go back to simplicity, and approach everything globally.

User experience (UX)

The first prototype confirmed that we needed a static site that could provide a good UX especially on mobile (which wasn’t that good in the existing site) and good SEO out of the box.

Maintenance

Reducing maintenance time and complexity was one of our main concerns.

We needed a simpler solution to maintain and deploy; we wanted to rely on existing and widely used tools (a lot of products have the same documentation needs as ours, so solutions exist for our use case), and reduce customization at the minimum (theming).

The Bonita Documentation site 2016 version worked perfectly for porting documentation content changes from version to version. We wanted to keep that, but have a simpler build that wouldn’t be split across repositories.

For a long time, keeping Markdown as a markup language was mandatory. We wanted to avoid doing content migration and training documentation contributors, but this should not stop us from using a better adapted solution if it supports only other languages (as long as we can migrate the existing content and it is easy to learn). We wanted to have a markup language for text diff/merge with Git and Markdown was one way to achieve that.

Operations

We needed to get rid of silos, to have a more self-serve solution to avoid tickets, team synchronization issues, and bottlenecks.

This also meant using configuration as code as much as possible, and automation for continuous preview and deployment. So we imagined a more comprehensive solution where we would no longer operate the Continuous Integration/Deployment, search, and front-end servers ourselves.

We wanted to focus on using them, not on maintaining and upgrading them. So we felt that this would probably involve using a PAAS solution, to provide more features for High Availability and Content Delivery Network.

For the old Drupal solution, we decided we needed to find a way to keep the content but drop the related infrastructure, or be ready to definitively remove it.

Photo by Drew Beamer on Unsplash

Coming soon

This article presents the issues of the Bonita Documentation site 2016 version and why we needed to provide a refreshed site. In it, I have outlined both the issues and our “need to have” and “want to have” requirements to select a new solution for improvements.

In the next article, we’ll explain the actual technical choices we made for the new online documentation, and what we learned about our new technical stack from the migration. (Hint: we’re still here, and so is the Bonita documentation!)

The story of Bonita Documentation! From Drupal to GitHub

Thomas Bouffard — Tue, 30 Nov 2021 15:38:45 +0000

Have you ever had a question, an issue, a need to know something about Bonita? If yes, you’ve probably visited the friendly Bonita Documentation!

Last March 2021, we launched the new Bonita Documentation site, which provides a lot of fixes and improvements. If you want more details about the new site content, here’s the site go live announcement.

We want to share with you the story of the Bonita documentation evolution. We’ll start with this article, first in a series to explain how and why the Bonitasoft team decided to make this latest change.

Here we’ll describe the previous iteration of the Bonita documentation (may it rest in peace), the fascinating history of our documentation and some of the issues we faced over the time.

In the following articles, we’ll explain the solution we were looking for, the technical choices we made, and what we learned from our new technical stack during the migration.

Bonita documentation: Know the past, understand the present

The Bonita online documentation was revamped in 2016. The previous Drupal-based site was deprecated and a new site, fully custom made, was introduced to host the documentation starting with Bonita BPM v7.3.

This first revision was motivated by the existence of a lot of issues in the existing solution, including:

Content could only be updated by the Bonitasoft internal technical writer (a single person), so if you saw a simple typo, for instance, you had no way to fix it yourself. You had to reach the person responsible, or create a ticket. This was a bottleneck and led to a lack of ownership in particular by the Bonitasoft Product and R&D teams who never felt motivated to improve documentation because the process was too heavy.
Versioning was hard to manage, in particular reporting updates from version to version was difficult (and not possible to do automatically), which meant is was often forgotten and not in sync with the Bonita version release.
There was no real preview of the final rendering prior to publishing to production, which led to mistakes, rework and dissatisfaction.
Technical updates in the production environment were rare and painful. This Drupal site had been customized by the Bonitasoft IT Team, so Drupal updates needed custom code/configuration as well.
It was necessary for Bonita users to login to access the documentation, and we may have lost some potential Bonita users because of that. We definitely had users that did not Read The Friendly Documentation!

The development of a new documentation solution started in January 2016 to be ready for the Bonita BPM v7.3 release.

New and improved!

The internal Bonitasoft team decided that the documentation content should be public and hosted in a GitHub repository.

We introduced with the GitHub documentation:

collaborative contribution flow with Pull Requests only
content is written using Markdown syntax instead of filling a form using pseudo-wysiwyg text. This separation between the content and its presentation allowed more flexibility (initially we could generate documentation in both PDF and HTML)
updated content is continuously deployed to production
a new and better search engine is integrated within the site
no more login is needed to access to the documentation
preview environments are available and built in the same way as the production

Photo by Jeremy Bezanger on Unsplash

These improvements fixed the main issues of the previous Drupal solution.

For Bonita users (community or customers), Bonita Documentation site v2016 meant that:

The documentation content was updated frequently, with a version-to-version report with a Git merge. Small changes could be done by anyone and pushed to production quickly by merging pull requests (and just a few minutes’ wait for the production site to be updated).
The documentation was released at the same time as the Bonita beta and GA versions.
Bonita users can contribute directly to the content instead of requesting changes (in particular for very small changes like typos).

For Bonita developers, Bonitasoft Product and Support Teams:

They can easily produce and update Bonita documentation.
Documentation issues and feedback can be quickly integrated.
Contributions are reviewed and discussed by technical pairs to be sure content is accurate.
Updates are tracked in the Git history for easier content maintenance.

The go live for Bonita documentation on GitHub was announced with a blog post on September 14, 2016, and this solution was used until March 2021.*

Photo by Drew Beamer on Unsplash

Coming soon

Then...everything changed once again. In my next blog post, I’ll tell you why.

Thank you to Laurent Leseigneur and Emmanuel Duchastenier for their review of this article.

*If you want to know more about this first migration, an overall presentation in French is available in a set of public slides (use the down arrow to pass to the next slide). It gives more details about this story, and the technical solution.

Embed Bonita Engine in a Spring Boot application

Emmanuel Duchastenier — Fri, 12 Jul 2019 12:50:09 +0000

This tutorial is an example of how to embed the Bonita Engine (BPM workflow engine) in a Spring Boot application.

The proposed use-case is an application based on a process that allows someone to request a loan from their bank. This request will be reviewed, approved or rejected by the bank which will give explanations for this decision.

Scope

In this tutorial, you will learn how to write an application, using the Spring Boot framework, that integrates the Bonita Execution Engine to run processes.
You will learn how to configure the Bonita Engine to point to the database of your choice and tune the connection pool.
You will learn how to build processes programmatically, deploy and execute them.
You will also learn how to deploy processes generated with Bonita Studio.

TLDR;

The full source code of this tutorial can be accessed directly, in 2 different flavours:

The first example illustrates how to build the application with Gradle.
The second example illustrates how to build the application with Maven. The full tutorial details are provided in the Gradle example, but everything works the same in the Maven example. Only the build part is specific.

Prerequisites

Database

If you just want to run an embedded H2 database, nothing is required.

To have your application point to a MySQL, PostgreSQL, Microsoft SQL Server, or Oracle database make sure you have a Database server up and running, and that it contains a schema dedicated to the Bonita Engine (default name is bonita).

For deeper details on database preparation for Bonita, see the specific documentation page.

Then read below how to configure the database access.

Processes

This tutorial assumes you have basic knowledge of BPMN / process design.

Use case

For this example, we will develop and interact with the following process.

Let's write the application step by step

In this example, we propose to use Gradle as the build tool, and Kotlin as the programming language.
If you are not familiar with Gradle, there is a Maven version of this example.
If you are not familiar with Kotlin, don't worry, it can be read easily if you know Java or a similar language.

Bootstrap of the application, using Spring Boot

Let's write a Gradle build (file build.gradle.kts) with the minimum Spring Boot + Kotlin requirements:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    id("org.springframework.boot") version "2.1.6.RELEASE"
    id("io.spring.dependency-management") version "1.0.7.RELEASE"
    kotlin("jvm") version "1.3.41"
    kotlin("plugin.spring") version "1.3.41"
}

repositories {
    mavenCentral()
    jcenter()
}

dependencies {
    // Embed an application server:
    implementation("org.springframework.boot:spring-boot-starter")

    // Libs to code in Kotlin:
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")
}

java.sourceCompatibility = JavaVersion.VERSION_1_8

// configure Kotlin compiler:
tasks.withType<KotlinCompile> {
    kotlinOptions {
        freeCompilerArgs = listOf("-Xjsr305=strict")
        jvmTarget = "1.8"
    }
}

Write the main Spring Boot class to launch our application:

package org.bonitasoft.loanrequest

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class LoanRequestApplication

fun main(args: Array<String>) {
    runApplication<LoanRequestApplication>(*args)
}

In the current state, our application can already be run (but does not do anything) by typing in the command line:

./gradlew bootRun

and can then be accessed at http://localhost:8080/

Adding the Bonita Engine

As a next step, let's add the Bonita Engine in the equation in our build.gradle.kts:

...
dependencies {
    ...
    val bonitaEngineVersion = "7.9.0"

    // adding dependency on bonita-engine-spring-boot-starter automatically provides
    // and starts a Bonita Engine when used in a Spring Boot application:
    implementation("org.bonitasoft.engine:bonita-engine-spring-boot-starter:$bonitaEngineVersion")

    // use bonita-client to be able to interact with the running Engine
    // to deploy and run instances of processes:
    implementation("org.bonitasoft.engine:bonita-client:$bonitaEngineVersion")

    // Add the database driver we want Bonita to use:
    runtime("com.h2database:h2:1.4.199")
    ...
}

The magic of Spring Boot happens, and a Bonita Engine is automatically started when our application starts.
We can see Engine startup logs in the console:

|09:44:15.601|main|INFO |o.b.p.s.ScriptExecutor| configuration for Database vendor: h2
|09:44:15.989|main|INFO |o.b.p.s.PlatformSetup| Connected to 'h2' database with url: 'jdbc:h2:file:./build/h2_database/bonita' with user: 'BONITA'
|09:44:16.341|main|INFO |o.b.p.s.ScriptExecutor| Executed SQL script file:/home/manu/.gradle/caches/modules-2/files-2.1/org.bonitasoft.platform/platform-resources/7.9.0/c183cb/platform-resources-7.9.0.jar!/sql/h2/createTables.sql
...
|09:44:26.437|main|INFO |o.b.e.a.i.PlatformAPIImpl| THREAD_ID=1 | HOSTNAME=manu-laptop | Start service of platform : org.bonitasoft.engine.classloader.ClassLoaderServiceImpl
|09:44:26.438|main|INFO |o.b.e.a.i.PlatformAPIImpl| THREAD_ID=1 | HOSTNAME=manu-laptop | Start service of platform : org.bonitasoft.engine.cache.ehcache.PlatformEhCacheCacheService
|09:44:26.490|main|INFO |o.b.e.a.i.PlatformAPIImpl| THREAD_ID=1 | HOSTNAME=manu-laptop | Start service of platform : org.bonitasoft.engine.service.BonitaTaskExecutor
...
|09:44:26.708|main|INFO |o.b.e.a.i.t.SetServiceState| THREAD_ID=1 | HOSTNAME=manu-laptop | TENANT_ID=1 | start tenant-level service org.bonitasoft.engine.cache.ehcache.EhCacheCacheService on tenant with ID 1
|09:44:26.718|main|INFO |o.b.e.a.i.t.SetServiceState| THREAD_ID=1 | HOSTNAME=manu-laptop | TENANT_ID=1 | start tenant-level service org.bonitasoft.engine.business.data.impl.JPABusinessDataRepositoryImpl on tenant with ID 1

Let's code our first process

Our platform is running, we can now create a LoanRequestProcessBuilder class that builds a Bonita process and returns a DesignProcessDefinition.
Let's build the process designed on the diagram above.

package org.bonitasoft.loanrequest.process

// imports removed for readability

const val ACTOR_REQUESTER = "Requester"
const val ACTOR_VALIDATOR = "Validator"

const val START_EVENT = "Start Request"
const val REVIEW_REQUEST_TASK = "Review Request"
const val DECISION_GATEWAY = "isAccepted"
const val SIGN_CONTRACT_TASK = "Sign contract"
const val NOTIFY_REJECTION_TASK = "Notify rejection"
const val ACCEPTED_END_EVENT = "Accepted"
const val REJECTED_END_EVENT = "Rejected"

const val CONTRACT_AMOUNT = "amount"

class LoanRequestProcessBuilder {

    fun buildExampleProcess(): DesignProcessDefinition {
        val processBuilder = ProcessDefinitionBuilder().createNewInstance("LoanRequest", "1.0")
        // Define the actors of the process:
        processBuilder.addActor(ACTOR_REQUESTER, true) // only requester can initiate a new process
        processBuilder.addActor(ACTOR_VALIDATOR) // only requester can initiate a new process
        // Define the tasks
        processBuilder.addUserTask(REVIEW_REQUEST_TASK, ACTOR_VALIDATOR)
        processBuilder.addUserTask(SIGN_CONTRACT_TASK, ACTOR_REQUESTER) // Imagine this task involve paper signing

        // For completion, this auto-task should have a connector on it,
        // to notify the rejection (through email connector, for example):
        processBuilder.addAutomaticTask(NOTIFY_REJECTION_TASK)

        // Define the events:
        processBuilder.addStartEvent(START_EVENT)
        processBuilder.addEndEvent(ACCEPTED_END_EVENT)
        processBuilder.addEndEvent(REJECTED_END_EVENT)
        // Define the Gateway:
        processBuilder.addGateway(DECISION_GATEWAY, GatewayType.EXCLUSIVE)
        // Define transitions:
        processBuilder.addTransition(START_EVENT, REVIEW_REQUEST_TASK)
        processBuilder.addTransition(REVIEW_REQUEST_TASK, DECISION_GATEWAY)
        processBuilder.addTransition(DECISION_GATEWAY, SIGN_CONTRACT_TASK,
                // let's simulate a human decision with a random accepted / rejected decision:
                ExpressionBuilder().createGroovyScriptExpression("random decision", "new java.util.Random(System.currentTimeMillis()).nextBoolean()", "java.lang.Boolean")
        )
        processBuilder.addDefaultTransition(DECISION_GATEWAY, NOTIFY_REJECTION_TASK) // Default transition, taken is expression above returns false
        processBuilder.addTransition(SIGN_CONTRACT_TASK, ACCEPTED_END_EVENT)
        processBuilder.addTransition(NOTIFY_REJECTION_TASK, REJECTED_END_EVENT)

        // Define a contract on the process initiation:
        processBuilder.addContract().addInput(CONTRACT_AMOUNT, Type.DECIMAL, "Amount of the loan requested")
        // Here we imagine a more complex contract with more inputs...

        return processBuilder.process
    }

}

Then this process must be deployed and enabled. Let's create a dedicated class:

package org.bonitasoft.loanrequest.process

// imports...

class ProcessDeployer {

    @Throws(BonitaException::class)
    fun deployAndEnableProcessWithActor(designProcessDefinition: DesignProcessDefinition,
                                        requesterActor: String,
                                        requesterUser: User,
                                        validatorActor: String,
                                        validatorUser: User): ProcessDefinition {
        // Create the Actor Mapping with our Users:
        val requester = Actor(requesterActor)
        requester.addUser(requesterUser.userName)
        val validator = Actor(validatorActor)
        validator.addUser(validatorUser.userName)
        val actorMapping = ActorMapping()
        actorMapping.addActor(requester)
        actorMapping.addActor(validator)

        // Create the Business Archive to deploy:
        val businessArchive = BusinessArchiveBuilder().createNewBusinessArchive()
                .setProcessDefinition(designProcessDefinition)
                // set the actor mapping so that the process is resolved and can then be enabled:
                .setActorMapping(actorMapping)
                .done()

        with(apiClient.processAPI) {
            val processDefinition = deploy(businessArchive)
            enableProcess(processDefinition.id)
            return processDefinition
        }
    }
}

Let's now call our build and deploy methods from our main application:

val apiClient = APIClient()

// Log in on Engine API:
loginAsTenantAdministrator()
// Create business users to interact with the process:
val requester = createNewUser("requester", "bpm", "Requester", "LoanRequester")
val validator = createNewUser("validator", "bpm", "Validator", "LoanValidator")
// Use this newly created users to create and execute the process flow:
loginWithAnotherUser(requester)
val processDefinition = createAndDeployProcess(requester, validator)

// Utility function to log in to Bonita with the provided Administrator User:
private fun loginAsTenantAdministrator() {
    apiClient.logout()
    apiClient.login(TENANT_ADMIN_NAME, TENANT_ADMIN_PASSWORD)
}

// Utility function to create a User in Bonita:
private fun createNewUser(userName: String, password: String, firstName: String, lastName: String): User {
    return apiClient.identityAPI.createUser(userName, password, firstName, lastName)
}

// Utility function to log in to Bonita with a specific User:
private fun loginWithAnotherUser(newUser: User) {
    apiClient.logout()
    apiClient.login(newUser.userName, "bpm")
}

private fun createAndDeployProcess(initiator: User, validator: User): ProcessDefinition {
    // Create the process:
    val designProcessDefinition = LoanRequestProcessBuilder().buildExampleProcess()
    // Deploy the process and enable it:
    return ProcessDeployer().deployAndEnableProcessWithActor(
            designProcessDefinition, ACTOR_REQUESTER, initiator, ACTOR_VALIDATOR, validator)
}

At this point, our process is created and deployed in Bonita.
Let's check this by writing a HTTP endpoint that lists all existing processes.
To do so, we need to add a simple Spring Boot dependency and its JSON library, to return the results in JSON format:
In this file build.gradle.kts, in the dependencies { } section

    // Libs to expose Rest API through an embedded application server:
    implementation("org.springframework.boot:spring-boot-starter-web:2.1.6.RELEASE")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.9.8")

Now we can write a simple Spring MVC controller to expose our processes through an HTTP API:

package org.bonitasoft.loanrequest.api

import org.bonitasoft.engine.api.APIClient
import org.bonitasoft.engine.bpm.process.ProcessDeploymentInfo
import org.bonitasoft.engine.search.SearchOptionsBuilder
import org.bonitasoft.loanrequest.process.CONTRACT_AMOUNT
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.RestController

@RestController
// our apiClient is automagically :-) injected by Spring:
class ProcessController(val apiClient: APIClient) {

    // Expose the deployed processes through Rest APIs:
    @GetMapping("/processes")
    fun list(): List<ProcessDeploymentInfo> {
        apiClient.login("install", "install")
        val result = apiClient.processAPI.searchProcessDeploymentInfos(SearchOptionsBuilder(0, 100).done()).result
        apiClient.logout()
        return result
    }
}

Finally, let's restart our application with ./gradlew bootRun.
Our application starts, creates and deploys our process.
Let's access http://localhost:8080/processes to list our processes. The result should be something like:

[
    {
        "id": 1,
        "name": "LoanRequest",
        "version": "1.0",
        "displayDescription": null,
        "deploymentDate": "2019-07-05T09:33:21.490+0000",
        "deployedBy": 1,
        "configurationState": "RESOLVED",
        "activationState": "ENABLED",
        "processId": 7450221031288910000,
        "displayName": "LoanRequest",
        "lastUpdateDate": "2019-07-05T09:33:21.607+0000",
        "iconPath": null,
        "description": null
    }
]

Beware that the field "processId" is incorrect, due to a limitation of the JSON / Javascript Long size, which is smaller that the Long size in Java (or Kotlin). The symptom is that the last digits are 0000 instead of a real value.
This limitation only exists if you use JSON / Javascript to display a Long value.
To bypass this limitation, we could convert this value as a String before returning it through Rest APIs.

Deploy a process designed with Bonita Studio

If you have designed your process using Bonita Studio (graphical tool), you can deploy the generated .bar file through the APIs as well. To do so, place your .bar file somewhere in the classpath of the application and load it like this:

class ProcessLoader {
    fun loadProcessFromBar(barFilePath: String): BusinessArchive {
        this.javaClass.getResourceAsStream(barFilePath).use { resourceAsStream ->
            return BusinessArchiveFactory.readBusinessArchive(resourceAsStream)
        }
    }
}

and make the call to the "load" function and then deploy:

val processFromBar = ProcessLoader().loadProcessFromBar("/SimpleProcess--1.0.bar")
ProcessDeployer().deployAndEnableBusinessArchiveWithoutAnyActor(processFromBar)

We can see that our process named SimpleProcess is now deployed:

|15:50:59.107|main|INFO |o.b.e.b.BusinessArchiveServiceImpl| THREAD_ID=1 | HOSTNAME=Ubuntu | TENANT_ID=1 | The user <requester> has installed process <SimpleProcess> in version <1.0> with id <6733385816066783268>
|15:50:59.119|BonitaTaskExecutor|INFO |o.b.e.c.ClassLoaderServiceImpl| THREAD_ID=60 | HOSTNAME=Ubuntu | Refreshing classloader with key: PROCESS:6733385816066783268
|15:50:59.200|main|INFO |o.b.e.a.i.t.p.EnableProcess| THREAD_ID=1 | HOSTNAME=Ubuntu | TENANT_ID=1 | The user <requester> has enabled process <SimpleProcess> in version <1.0> with id <6733385816066783268>

The full example can be found in the source code.

Warning: be aware that a .bar file generated by a specific Studio version is compatible only with the same version of Bonita you imported in your Gradle dependencies. If you update the dependency to a newer version, you may need to regenerate the .bar file with the same newer version of Bonita Studio.

Interact with the process

Our platform and process are now ready to be executed.
We have to set interactions with the process to continue the execution flow.
The interactions depend on the design of our process.
Here is an example of the application flow:

...
executeProcess(requester, validator, processDefinition)

@Throws(BonitaException::class)
fun executeProcess(initiator: User, validator: User, processDefinition: ProcessDefinition) {
    // Start a new Loan request with an amount of 12000.0 (€ Euro):
    val processInstance = apiClient.processAPI.startProcessWithInputs(processDefinition.id, mapOf(Pair(CONTRACT_AMOUNT, 12000.0)))

    // Now the validator needs to review it:
    loginWithAnotherUser(validator)
    // Wait for the user task "Review Request" to be ready to execute, using a user member of "Validator" actor:
    val reviewRequestTask = waitForUserTask(validator, processInstance.id, REVIEW_REQUEST_TASK)

    // Take the task and execute it:
    apiClient.processAPI.assignAndExecuteUserTask(validator.id, reviewRequestTask.id, emptyMap())

    // If the request has been accepted, wait for the "Sign contract" task to be ready and execute it:
    val signContractTask = waitForUserTask(initiator, processInstance.id, SIGN_CONTRACT_TASK)
    apiClient.processAPI.assignAndExecuteUserTask(initiator.id, signContractTask.id, emptyMap())

    // Wait for the whole process instance to finish executing:
    waitForProcessToFinish()

    println("Instance of Process LoanRequest(1.0) with id ${processInstance.id} has finished executing.")
}

// Utility function to wait for a User task to be ready:
fun waitForUserTask(user: User, processInstanceId: Long, userTaskName: String): HumanTaskInstance {
    Awaitility.await("User task should not last so long to be ready :-(")
            .atMost(TEN_SECONDS)
            .pollInterval(FIVE_HUNDRED_MILLISECONDS)
            .until(Callable<Boolean> {
                apiClient.processAPI.getNumberOfPendingHumanTaskInstances(user.id) == 1L
            })
    return apiClient.processAPI.getHumanTaskInstances(processInstanceId, userTaskName, 0, 1)[0]
}

// Utility function to wait for a process to be completed:
fun waitForProcessToFinish() {
    Awaitility.await("Process instance lasts long to complete")
            .atMost(TEN_SECONDS)
            .pollInterval(FIVE_HUNDRED_MILLISECONDS)
            .until(Callable<Boolean> {
                apiClient.processAPI.numberOfArchivedProcessInstances == 1L
            })
}

Bonus: cherry on the top

Spring Boot allows you to easily tune the banner that is displayed when an application starts.
Simply put a banner.txt file in the resources folder with some ASCII art:

 _                        ______                           _
| |                       | ___ \                         | |
| |     ___   __ _ _ __   | |_/ /___  __ _ _   _  ___  ___| |_
| |    / _ \ / _` | '_ \  |    // _ \/ _` | | | |/ _ \/ __| __|
| |___| (_) | (_| | | | | | |\ \  __/ (_| | |_| |  __/\__ \ |_
\_____/\___/ \__,_|_| |_| \_| \_\___|\__, |\__,_|\___||___/\__|
                                        | |
                                        |_|

Expose business monitoring on our application flow

Maybe we want our application to expose APIs to be able to follow the flow of our processes.
Simply add the following Rest Controller class to expose the running and completed cases (process instances):

package org.bonitasoft.loanrequest.api

import org.bonitasoft.engine.api.APIClient
// ...
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@RestController
class CaseController(val apiClient: APIClient) {

    // Expose the open process instances (=cases not completed)
    @GetMapping("/cases")
    fun list(): List<ProcessInstance> {
        apiClient.login("install", "install")
        try {
            return apiClient.processAPI
                    .searchOpenProcessInstances(SearchOptionsBuilder(0, 100).done())
                    .result
        } finally {
            apiClient.logout()
        }
    }

    // Expose the finished process instances (=cases completed)
    @GetMapping("/completedcases")
    fun listCompleted(): List<ArchivedProcessInstance> {
        apiClient.login("install", "install")
        try {
            return apiClient.processAPI
                    .searchArchivedProcessInstances(SearchOptionsBuilder(0, 100).done())
                    .result
        } finally {
            apiClient.logout()
        }
    }

}

Similarly, to expose the tasks ready to execute, add the following Rest Controller class:

package org.bonitasoft.loanrequest.api

// ...
import org.springframework.web.bind.annotation.PathVariable
import org.springframework.web.bind.annotation.RestController

@RestController
class TaskController(val apiClient: APIClient) {

    @GetMapping("/tasks")
    fun list(): List<HumanTaskInstance>? {
        apiClient.login("install", "install")
        val result = apiClient.processAPI.searchMyAvailableHumanTasks(
                apiClient.session.userId,
                SearchOptionsBuilder(0, 100).done())
                .result
        apiClient.logout()
        return result
    }
}

Full example

This repository contains the full code of this example, ready to build / run.

Build your application

Run ./gradlew build to build the binaries. It will generate a jar file in build/libs/ folder.

Run your application

Simply run the gradle command:

./gradlew bootRun

or run the previously-built jar file:

java -jar build/libs/bonita-loan-request-application.jar

You can then access the list of processes by opening a web browser at http://localhost:8080/processes.
The list of cases (process instances) is available at http://localhost:8080/cases.
The list of finished cases (completed process instances) is available at http://localhost:8080/completedcases.
The list of tasks is available at http://localhost:8080/tasks.

Configure the database

When nothing is specified, an embedded H2 database is created and used.
To use a different database, in folder resources create a standard Spring Boot configuration file named application.properties (or .yaml)
and set the following properties. Here is an example with PostgreSQL:

# specify the database vendor you wish to use (supported values are h2, mysql, postgres, sqlserver, oracle):
org.bonitasoft.engine.database.bonita.db-vendor=postgres
# specify the URL to connect to your database:
org.bonitasoft.engine.database.bonita.url=jdbc:postgresql://localhost:5432/bonita

# specify the connection user to the database:
org.bonitasoft.engine.database.bonita.user=bonita
# specify the connection password to the database:
org.bonitasoft.engine.database.bonita.password=bpm
org.bonitasoft.engine.database.bonita.datasource.maxPoolSize=3

# specify a different AppServer port if required:
server.port=8080

The provided application.properties file contains examples for all database vendors.

Finally, don't forget to replace the default H2 dependency for your PostgreSQL drivers in file build.gradle.kts:

    // runtime("com.h2database:h2:1.4.199")
    // runtime("mysql:mysql-connector-java:8.0.14")
     runtime("org.postgresql:postgresql:42.2.5")
    // runtime("com.microsoft.sqlserver:mssql-jdbc:7.2.1.jre8")
    // Oracle database drivers are not open-source and thus cannot be included here directly

A self-managed developers' team experience: what it was like

Emmanuel Duchastenier — Wed, 30 Jan 2019 08:59:47 +0000

About a year ago, I had the opportunity to start a project with a team designated to be self-managed by our manager. I enjoyed this way of working and I would like to share the advantages I appreciated.

This article shares a specific way of working we used at Bonitasoft. However, I believe it is suitable reading to anyone interested in methodologies, whether Agile or not. I will sometimes talk about technical tools and technologies that developers are familiar with, but this is definitely not mandatory to understand my points here.

Context

At Bonitasoft, our Continuous Integration environments (CI) were getting old: we were using Jenkins 2.0, configured with XML files under version control in a dedicated repository, which was separate from the repositories containing the source code to build and test.

Maintaining those environments was laborious. Not all of our developers shared the necessary knowledge, and it was not possible to scale easily when we had parallel developments (because of the team’s growth, or because we were becoming more productive!)

Five of us in the team really wanted to rewrite the whole thing from scratch, with newer tools and technologies.

We took the opportunity to create a new project and experience a new way of organising ourselves, with a methodology by developers, for developers.

The advantages of self-management

Autonomy is a mark of trust

Our manager constantly seeks ways to keep developers engaged. He felt that leaving us as much freedom as possible to lead and carry out this project was a way of keeping us motivated.

This did not mean we had no reviews to show other teams. On the contrary, every other week we had to demonstrate our progress, and most of the time, we were pretty proud of it.

Freedom to organise appropriately

At Bonitasoft, we use Atlassian Jira to manage our tasks, support tickets, bugs, and more. We decided not to introduce a new tool for this project.

However, we did decide to use a specific Jira Project (in the Jira meaning of “project”) for this initiative, with its specific workflow, that we deliberately chose to be light and non-restrictive. After all, our tools are here to serve us, not the contrary. We created our own dashboards to follow our progress.

This allowed us to easily create as many tickets as we needed, delete them when necessary, resolve them, and close them, without the pain of having to fill in many fields that would not necessarily match our workflow.

Our Kanban board with our lightweight workflow.

Freedom to choose our tools

Rewriting a whole Continuous Integration environment for the entire R&D team is a lot of work, and choosing the right tools for the job was key. We took time for technological research. We investigated several tools, framework, ways of implementing security, means of writing proper Jenkins jobs / pipelines, and so on. We also became “experts” on Docker containers and their integration with tools like Gradle.

The freedom - and responsibility - of choosing the proper technologies allowed us to train ourselves with some cutting-edge, current, trendy technologies. We also feel very proud of what we have achieved with these tools.

Everyone shares the same level of knowledge

There was nothing revolutionary in the contribution workflow. Like everywhere else at Bonitasoft, contributions are made via basic Github Pull Request review workflow, very familiar to developers (not just at Bonitasoft, but pretty widely).

Where we decided to innovate was to do our contribution reviews together as a group, and the decision to merge each Github Pull Request was agreed upon together as well. This might look like a strong constraint, but the benefit is huge: the main contributor gets the chance to explain the technology discovered, the difficulties encountered, why this implementation was considered the best option. The reviewers get the chance to ask questions, propose improvements - and discover new stuff.

Merging a contribution was done when everyone agreed.

If the contribution needed to be shared with developers in other teams, it was explained or demonstrated during the next advancement status, or in a dedicated technical talk, if appropriate.

Freedom to be as involved as needed

With five in the team, we had the option to shift our engagement, to have times to be more involved in developing the tasks we agreed to work on, and other times to pull back and just follow and review the developments made by others.

This allowed us all to work according to our interests and individual schedules, and keep each other motivated by working on items we were really excited about.

Problems encountered and how we managed them

Keeping CI environments up-to-date and adapted to our evolving needs is a never-ending project.

As with many long-term projects, keeping motivation up all the time is not easy. There were moments where little work was done from one week to the next, because the tasks were not the that interesting or exciting to work on, or because we were working on other concurrent priorities.

However, having the option to be less involved from time to time, and then come back later with more enthusiasm to try new things allowed us to have a good overall delivery rate, as well as pride in the work we accomplished.

Recommendations for success with this approach

Don’t stick with something you took that worked and seemed trendy at the time, but that does not fill the bill later on.

For example, we tested and used a Jenkins plugin that allowed us to provision Docker containers on the fly. We were happy using it for a while. Then came the moment when when needed to use it at a larger scale, and we decided it was not the right tool for the job. So we simply changed to another implementation.

My point here is that you shouldn’t hesitate to change, remove, or refactor something that you thought was exactly right 2 months earlier. Constant reassessment is normal in software development. It is ultimately more important to adapt the tool to the needs, than to preserve our pride.

Here’s what I feel are key requirements for a successful team:

Self-managed team members should be able to choose to work together, not be selected by an outside person to create a team
Self-managed teams must accept that some team members will not be involved as much as others, and this is not a problem. In fact it can be an advantage.
Working as a self-managed team can only be successful if you have the full trust of your manager that you know what to do and how to work best together.

Summary

I have been working on a self-managed team for a year now, and I still am.

It’s great to have had the chance to experience so much freedom.

I’m proud of the work I’ve been able to contribute on an individual level, and even more proud of the work we’ve done as a team.

And technically, I have grown and learned a great deal through sharing with my coworkers.

I recommend every developer who loves what they do to try working in a self-managed team - try it if you can and see how it works for you.