= Configure connection to Bonita Engine
:description: Learn how to configure your application to connect to a remote Bonita Engine, in order to access Engine APIs

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_config]

== 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 https://javadoc.bonitasoft.com/api/{javadocVersion}/org/bonitasoft/engine/util/APITypeManager.html[Javadoc].

Here is an example of programmatic configuration to an engine

[source,java]
----
HashMap<String,String> parameters= new HashMap<>();
parameters.put("server.url", "http://myserver.com:8080");
parameters.put("application.name", "bonita-application");
APITypeManager.setAPITypeAndParams(ApiAccessType.HTTP, parameters)
----

=== Configure Client using System properties

You can set the system property `org.bonitasoft.engine.api-type` to `HTTP` or `LOCAL`.

* `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`

+
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.

[WARNING]
====

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

[IMPORTANT]
====

Deprecated, use the programmatic way instead, see https://javadoc.bonitasoft.com/api/{javadocVersion}/org/bonitasoft/engine/util/APITypeManager.html[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.

[source,properties]
----
###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 xref:tomcat-bundle.adoc[Tomcat bundle] is configured to accept connection for HTTP connections.

It is configured in the `web.xml` file of the web application like this:

[source,xml]
----
<servlet>
    <servlet-name>HttpAPIServlet</servlet-name>
    <servlet-class>org.bonitasoft.engine.api.internal.servlet.HttpAPIServlet</servlet-class>
</servlet>
----

[WARNING]
====

This HTTP access  is not secured, it should not be exposed outside a trusted area. We recommend you to deactivate it if you expose directly your deployment to the outside world.
====
