Bonita Java Client

This project is the official web client for Bonita when working with Java (or on the JVM).

It is based on an OpenAPI specification for Bonita 7.15 Enterprise edition. This means that this client includes all Community operations plus some that are only supported by Enterprise editions servers.

---

1. Features

• Cover publicly available http endpoints of Bonita Platform 7.15 and onwards

• Built-in Bonita authentication support (SSO not supported yet)

• Higher level code than raw openapi client to ease developer journey

2. Getting started

The client library available from Maven Central, you can use it in your Maven project by adding the following to your pom.xml:

<dependency>
    <groupId>org.bonitasoft.web</groupId>
    <artifactId>bonita-java-client</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>

📎	Snapshots versions are available at https://oss.sonatype.org/content/repositories/snapshots/

The following code creates a java client instance targeting a bonita server listening at http://localhost:8080/bonita. After login in, it queries the deployed processes with pagination parameters (page index: 0,page size: 20)

// Create a client
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita").build();

// Login
Session session = client.login("username","password");
// Log Bonita server version
log.debug("Bonita version: {}", session.getVersion());

// Use the client 🥳
List businessProcesses = client.processes().searchProcesses(0, 20);

// Logout when done
client.logout();

3. Configuration

3.1. Logging

This client can log HTTP requests made to Bonita Platform.

Different log level are available. Default level is OFF

• FULL: Headers + Body

• HEADER: Headers

• BASIC: HTTP trace (url + verb + response code)

• OFF: No log

BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        .logContentLevel(LogContentLevel.BASIC)
    .build();

The logger name is org.bonitasoft.web.client.BonitaClient and logging is done with to slf4j so if you’re using logback implementation, you may configure your logger like this :

<logger name="org.bonitasoft.web.client.BonitaClient" level="INFO"/>

3.2. http timeouts

The following code show how you can customize the client http timeouts.

BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        .connectTimeoutInSeconds(int connectTimeoutInSeconds)
        .readTimeoutInSeconds(int readTimeoutInSeconds)
        .writeTimeoutInSeconds(int writeTimeoutInSeconds)
    .build();

3.3. SSL

If you need for any reason to disable ssl certificate check, here is the code to do it:

BonitaClient client = BonitaClient.builder("https://me.bonitacloud.com/")
        // Disable certificate check
        .disableCertificateCheck(true)
    .build();

⚠️	Please note that this is not recommended from a security point of view !

3.4. Custom Jackson object mapper

// Create your custom ObjectMapper
ObjectMapper myObjectMapper = new ObjectMapper();

// Configure bonita client to use your custom ObjectMapper
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        .objectMapper(myObjectMapper)
    .build();

3.5. Custom OkHttp Client

// Create your custom OkHttp client
OkHttpClient myOkHttpClient = new OkHttpClient.Builder().build();

// Configure bonita client to use your custom OkHttp client
BonitaClient client = BonitaClient.builder("http://localhost:8080/bonita")
        okHttpClient(myOkHttpClient)
    .build();

3.6. Custom Feign configuration

The current implementation of the client use OpenFeign internally. If you need to fine tune the feign aspect, it is possible but remember this may change in future version.

// Create your custom feign builder
Feign.Builder myFeignBuilder = new Feign.Builder();

BonitaClientBuilder builder = BonitaClient.builder("http://localhost:8080/bonita");
// Cast builder to BonitaFeignClientBuilder class
BonitaFeignClientBuilder bonitaClientBuilder = (BonitaFeignClientBuilder) builder;
BonitaClient client = bonitaClientBuilder
        // Configure bonita client to use your custom feign builder
        .feignBuilder(myFeignBuilder)
    .build();

4. Samples

4.1. BDM typed queries

Bonita allow users to define their own custom "named" queries. That’s why this client can’t have java object ready to be mapped to the query results. But the client allow developers to specify the desired returned type when performing custom queries.

As an example, let’s say with have a model in our client project code for Post,Comment and Author defined this way

public interface Post {
    Author getAuthor();
    String getTitle();
    String getContent();
    List<Comment> getComments();
}

public interface Comment {
    Long getUserId();
    LocalDateTime getCreationDate();
	String getContent();
}

public class Author {
    private String firstName;
    private String lastName;
    // Getter and Setter omitted ...
}

Interface with Getter methods are a good choice since we consider the retrieved data as immutable.

Bonus, it allow for lazy fetch of relations as defined in the BDM !

// Count comment and map response to an Integer
Integer count = bonitaClient.bdm().querySingle("com.company.model.Comment", "countForFind", Integer.class);

// List comments and map response to a list of Comment
List<Post> posts = bonitaClient.bdm().query("com.company.model.Post", "find", Post.class);

Post post = posts.get(O);
// This will trigger an HTTP GET request to get the related comments from the BDM
List<Comment> comments = post.getComments();

If you prefer a map style like approach, you can still use the BusinessData class.

List<BusinessData> comments = bonitaClient.bdm().query("com.company.model.Comment", "find", BusinessData.class);
String content = comments.get(0).get("content")

5. Developing

5.1. Prerequisite

• a git client

• a java (jdk8 or higher)

• maven (optional if you chose to use maven wrapper script)

• Docker for integration tests

5.2. Building

This is a standard maven project. To install the java client library to your local Maven repository, simply execute:

git clone https://github.com/bonitasoft/bonita-java-client.git
cd bonita-java-client/
mvn install

The build should produce under the target/ folder (and in your local maven repository) a jar archive named bonita-java-client-1.0.0-SNAPSHOT.jar

For more details about apache maven, please refer to the documentation

5.3. Format source code

This project uses Spotless to ensure a consistent formatting. To apply the configured formatting rules use the following Maven command:

./mvnw spotless:apply

5.4. Update OpenAPI spec version

The OpenAPI spec is retrieve from the [bonita-openapi](https://github.com/bonitasoft/bonita-openapi/) repository releases. To update the spec version you must:

• Update the bonita-openapi.version property in the pom.xml

• Run the following Maven command:

./mvnw groovy:execute@update-spec

You can then regenerate the feign stubs.

5.5. Regenerate feign stubs

If the openapi specification changed, you can regenerates the feign stubs with the following command.

⚠️	Be careful, some client stubs are marked as ignored in .openapi-generator-ignore file, since they were customized (like returning a feign.Response instead of a model object)

mvn generate-sources -Dcodegen.skip=false

5.6. Branches

The adopted worlfow is for now the Gitflow one.

Please refers to this article for more info: https://jeffkreeftmeijer.com/git-flow/

6. Release

• Create a branch for the desired version. ex: release/1.0.0. You can use the set-version.sh script to align declared versions in sources (pom.xml,readme.adoc,…​)

• Push branch, make a pull request to master and review release with others

• Once you are happy with the content of the release branch, merge pull request to master branch using Merge pull request button (⚠ Do not squash or rebase)

• Wait the build to succeed

• Go to https://oss.sonatype.org/ to close and release the staging repository and now you’re done ! 🥳

📎	Do not update your local dev branch after a release has been done ! The release job will perform the dev branch update itself !

7. Getting Help

The bonitasoft organization on GitHub hosts the project’s source code, issue trackers, and other projects.

Source repository (git)

https://github.com/bonitasoft/bonita-java-client

Issue tracker

https://github.com/bonitasoft/bonita-java-client/issues

Organization on GitHub

https://github.com/bonitasoft

8. Copyright and License

Use of this software is granted under the terms of the GNU GENERAL PUBLIC LICENSE.

See the LICENSE for the full license text.

9. Changelog

Refer to the CHANGELOG for a complete list of changes in older releases.

10. Links

• Project homepage: https://github.com/bonitasoft/bonita-java-client/

• Repository: https://github.com/bonitasoft/bonita-java-client/

• Issue tracker: https://github.com/bonitasoft/bonita-java-client/issues.
  In case of sensitive bugs like security vulnerabilities, please contact rd@bonitasoft.com directly instead of using issue tracker. We value your effort to improve the security and privacy of this project!

• Current Bonita REST API documentation: https://documentation.bonitasoft.com/bonita/7.15/rest-api-overview

• OpenAPI specification: https://swagger.io/specification/

• OpenAPI generator: https://github.com/OpenAPITools/openapi-generator

• OpenFeign: https://github.com/OpenFeign/feign

• slf4j: http://www.slf4j.org/

• Jackson ObjectMapper: https://github.com/FasterXML/jackson-databind