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.
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
LOCAL as shown in the examples above.
HTTPconnection mode will connect the client to the engine using the http protocol. This is the most common way to connect to engine remotely.
HTTPmode, 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
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.
true): it is now mandatory to connect to the engine through HTTP
http-api): the username to connect to the engine through HTTP, configured server-side in file <BONITA>/server/conf/tomcat-users.xml
h11p-@p1in 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
LOCALThis 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
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 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
setEnv.[sh|bat]inside tomcat bundle (in folder
or set an environment variable
HTTP_API=falsebefore launching Bonita Tomcat bundle