Configure connection to Bonita Engine

Learn how to configure your application to connect to a remote Bonita Engine, in order to access Engine APIs

If you want your application to use Bonita Engine APIs of a remote engine, your application (the client) must configure the connection to the remote engine (the server)

The engine (the server) must also be configured to accept the connection.

Client configuration

There is three ways to configure the client to connect to the Bonita Engine.

First the engine client verify if the configuration is set programmatically, then it tries to get the configuration set in system properties, finally it falls back to the legacy way of configuration that is the bonita home client.

Configure Client using programmatic configuration

You can configure the connection to the engine directly using org.bonitasoft.engine.util.APITypeManager, please refer to the Javadoc.

Here are some examples of programmatic configuration to an engine

HashMap<String,String> parameters= new HashMap<>();
parameters.put("server.url", "http://myserver.com:8080");
parameters.put("application.name", "bonita");
// HTTP Basic Auth is active by default on server-side:
parameters.put("basicAuthentication.active", "true");
parameters.put("basicAuthentication.username", "http-api");  // default value, can be changed server-side in file <BONITA>/server/conf/tomcat-users.xml
parameters.put("basicAuthentication.password", "h11p-@p1");  // default value, can be changed server-side in file <BONITA>/server/conf/tomcat-users.xml
APITypeManager.setAPITypeAndParams(ApiAccessType.HTTP, parameters);
System.setProperty("org.bonitasoft.engine.api-type", ApiAccessType.HTTP.name());
System.setProperty("org.bonitasoft.engine.api-type.server.url", "http://myserver.com:8080");
System.setProperty("org.bonitasoft.engine.api-type.application.name",  "bonita");
// HTTP Basic Auth is active by default on server-side:
System.setProperty("org.bonitasoft.engine.api-type.basicAuthentication.active", "true");
System.setProperty("org.bonitasoft.engine.api-type.basicAuthentication.username",  "http-api");  // default value, can be changed server-side in file <BONITA>/server/conf/tomcat-users.xml
System.setProperty("org.bonitasoft.engine.api-type.basicAuthentication.password", "h11p-@p1");   // default value, can be changed server-side in file <BONITA>/server/conf/tomcat-users.xml

Configure Client using System properties

You can set the system property org.bonitasoft.engine.api-type to HTTP or LOCAL as shown in the examples above.

  • HTTP: The HTTP connection mode will connect the client to the engine using the http protocol. This is the most common way to connect to engine remotely.
    When using HTTP mode, you must set the following system properties

    • org.bonitasoft.engine.api-type.server.url: it is the url of the server, e.g. for a engine on the same host it can be http://localhost:8080

    • org.bonitasoft.engine.api-type.application.name: it is the name of the web application on which the engine HTTP API is deployed, e.g. bonita

    • org.bonitasoft.engine.api-type.basicAuthentication.active (value true): it is now mandatory to connect to the engine through HTTP

    • org.bonitasoft.engine.api-type.basicAuthentication.username (default value: http-api): the username to connect to the engine through HTTP, configured server-side in file <BONITA>/server/conf/tomcat-users.xml

    • org.bonitasoft.engine.api-type.basicAuthentication.password (default value: h11p-@p1 in Tomcat bundle, no default value in Docker image): the password to connect to the engine through HTTP, configured server-side in file <BONITA>/server/conf/tomcat-users.xml

    In addition, starting from version 7.9.4, the number of connections used by the client can be configured with system property org.bonitasoft.engine.api-type.connections.max, the default is 20.

We do not guarantee to keep the http protocol stable, so we strongly recommend that you use the same version for both the client and the server

  • LOCAL This is the default connection mode, it connects to the server in the same JVM (not remote). If nothing is set this mode will be used.

Configure client using Bonita Home client

Deprecated, use the programmatic way instead, see APITypeManager.

This is a legacy way to configure the connection to the remote engine.

In this case you have to create a folder containing a engine-client directory and a conf subdirectory. This last subdirectory must contain a file named bonita-client-custom.properties having as content configuration of the engine client (see below). Finally, set the System property bonita.home to the root folder you created.

Here is the default content of this configuration file, uncomment the part of the file corresponding to the type of connection you want and customize it according to your application.

###template file
# LOCAL
org.bonitasoft.engine.api-type = LOCAL

# HTTP
#org.bonitasoft.engine.api-type = HTTP
#server.url = http://localhost:8080
#application.name = bonita
#connections.max = 20

Server configuration

Server configuration to accept HTTP Connection

By default, the Tomcat bundle is configured to accept connection over HTTP.

To deactivate HTTP connections:

  • either add a Java system property -Dhttp.api=false to file setEnv.[sh|bat] inside tomcat bundle (in folder setup/tomcat_templates/)

  • or set an environment variable HTTP_API=false before launching Bonita Tomcat bundle