camunda Connect Reference

camunda Connect provides a simple API for connecting HTTP Services and other things. It aims at two usage scenarios, usage in a generic system such as camunda BPM process engine and standalone usage via API.

Connect can be used in any Java-based application by adding the following maven dependency to your pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.camunda.connect</groupId>
      <artifactId>camunda-connect-bom</artifactId>
      <scope>import</scope>
      <type>pom</type>
      <version>${version.connect}</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.camunda.connect</groupId>
    <artifactId>camunda-connect-core</artifactId>
  </dependency>

  <dependency>
    <groupId>org.camunda.connect</groupId>
    <artifactId>camunda-connect-connectors-all</artifactId>
  </dependency>
</dependencies>

camunda Connect is published to maven central.

camunda Connect provides a HTTP and a SOAP HTTP connector. If you want to add an own connector to Connect please have a look at the extending Connect section. This section also describes the usage of a ConnectorConfigurator to configure the connector instances.

During the request invocation of a connecotr an interceptor chain is passed. The user can add own interceptors to this chain. The interceptor is called for every request of this connector.

connector.addRequestInterceptor(interceptor).createRequest();

camunda Connect uses camunda-commons-logging which itself uses SLF4J as a logging backend. To enable logging a SLF4J implementation has to be part of your classpath. For example slf4j-simple, log4j12 or logback-classic.

To also enable logging for the Apache HTTP client you can use a SLF4J bridge like jcl-over-slf4j as the Apache HTTP Client doesn't support SLF4J.

In camudna Connect a Connectors class exists which automatically detects every connector in the classpath. It can be used to get the HTTP connector instance by connector ID.

HttpConnector http = Connectors.getConnector(HttpConnector.ID);

Configure Apache HTTP Client

Camunda Connect HTTP client uses the Apache HTTP client to make HTTP requests. Accordingly, it supports the same configuration options.

Default Configuration

By default, the HTTP client uses Apache's default configuration and respects the system properties that are supported by HTTP client.

Custom Configuration

If you want to reconfigure the client going beyond the default configuration options, e.g. you want to configure another connection manager, the easiest way is to register a new connector configurator.

package org.camunda.connect.example;

import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.camunda.connect.httpclient.impl.AbstractHttpConnector;
import org.camunda.connect.spi.ConnectorConfigurator;

public class HttpConnectorConfigurator implements ConnectorConfigurator<HttpConnector> {

  public Class<HttpConnector> getConnectorClass() {
    return HttpConnector.class;
  }

  public void configure(HttpConnector connector) {
    CloseableHttpClient client = HttpClients.custom()
      .setMaxConnPerRoute(10)
      .setMaxConnTotal(200)
      .build();
    ((AbstractHttpConnector) connector).setHttpClient(client);
  }

}

To enable auto detection of your new configurator please add a file called org.camunda.bpm.connect.spi.ConnectorConfigurator to your resources/META-INF/services directory with class name as content. For more information see the extending Connect section.

org.camunda.connect.example.HttpConnectorConfigurator

Create a simple HTTP request

The HTTP connector can be used to create a new request, set a HTTP method, URL, content type and payload.

A simple GET request:

http.createRequest()
  .get()
  .url("http://camunda.org")
  .execute();

A POST request with a content type and payload set:

http.createRequest()
  .post()
  .url("http://camunda.org")
  .contentType("text/plain")
  .payload("Hello World!")
  .execute();

The HTTP methods PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE are also available.

Adding HTTP headers to a request

To add own headers to the HTTP request the method header is available.

HttpResponse response = http.createRequest()
  .get()
  .header("Accept", "application/json")
  .url("http://camunda.org")
  .execute();

Using the generic API

Besides the configuration methods also a generic API exists to set parameters of a request. The following parameters are available:

This can be used as follows:

HttpRequest request = http.createRequest();
request.setRequestParameter("method", "GET");
request.setRequestParameter("url", "http://camunda.org");
request.setRequestParameter("payload", "hello world!");

A response contains the status code, response headers and body.

Integer statusCode = response.getStatusCode();
String contentTypeHeader = response.getHeader("Content-Type");
String body = response.getResponse();

After the response was processed it should be closed.

response.close()

Using the generic API

Besides the response methods a generic API is provided to gather the response parameters. The following parameters are available:

This can be used as follows:

response.getResponseParameter("statusCode");
response.getResponseParameter("headers");
response.getResponseParameter("response");

In camunda Connect a Connectors class exists which automatically detects every connector in the classpath. It can be used to get the SOAP connector instance by connector ID.

SoapHttpConnector soap = Connectors.getConnector(SoapHttpConnector.ID);

The SOAP connector extends the camunda Connect HTTP connector, which uses the Apache HTTP client in the default implementation. To configure the client please see the corresponding section in the HTTP connector docs.

Creating a request

The SOAP HTTP connector can be used to create a new request, set a URL, content type and payload.

connector.createRequest()
  .url("http://camunda.org/soap")
  .soapAction("doIt")
  .contentType("application/soap+xml")
  .payload(soap_envelope)
  .execute();

Adding HTTP headers to a request

To add own headers to the HTTP request the method header is available.

connector.createRequest()
  .url("http://camunda.org/soap")
  .soapAction("doIt")
  .contentType("application/soap+xml")
  .header("Accept", "application/xml")
  .payload(soap_envelope)
  .execute();

Using the generic API

Besides the configuration methods also a generic API exists to set parameters of a request. The following parameters are available:

This can be used as follows:

HttpRequest request = http.createRequest();
request.setRequestParameter("method", "GET");
request.setRequestParameter("url", "http://camunda.org");
request.setRequestParameter("payload", "hello world!");

A response contains the status code, response headers and body.

Integer statusCode = response.getStatusCode();
String contentTypeHeader = response.getHeader("Content-Type");
String body = response.getResponse();

After the response was processed it should be closed.

response.close()

Using the generic API

Besides the response methods a generic API is provided to gather the response parameters. The following parameters are available:

This can be used as follows:

response.getResponseParameter("statusCode");
response.getResponseParameter("headers");
response.getResponseParameter("response");

The connectors available to Connect may not always suit your needs. Sometimes, it is necessary to provide configuration.

To configure a connector detected by Spin, the SPI org.camunda.connect.spi.ConnectorConfigurator can be implemented. A configurator specifies which classes it can configure. Connect discovers a configurator by employing Java's service loader mechanism and will then provide it with all connectors that match the specified class (or are a subclass thereof). The concrete configuration options depend on the actual connector. For example, the HTTP based connector can modify the Apache HTTP client that the connector uses.

In order to provide a custom configurator, you have to

• Provide a custom implementation of org.camunda.connect.spi.ConnectorConfigurator
• Add the configurator's fully qualified classname to a file named META-INF/services/org.camunda.connect.spi.ConnectorConfigurator
• Ensure that the artifact containing the configurator is reachable from Connect's classloader

A connector is an implementation of the interface org.camunda.connect.spi.Connector. An implementation of this interface can be registered by implementing the SPI org.camunda.connect.spi.ConnectorProvider. Connect uses the Java platform's service loader mechanism to lookup provider implementations at runtime.

In order to provide a custom connector, you have to

• Provide a custom implementation of org.camunda.connect.spi.Connector
• Provide a custom implementation of org.camunda.connect.spi.ConnectorProvider
• Add the provider's fully qualified classname to a file named META-INF/services/org.camunda.connect.spi.ConnectorProvider
• Ensure that the artifact containing the provider is reachable from Connect's classloader

If you now call org.camunda.connect.Connectors.getAvailableConnectors(), then the custom connector is returned along with the built-in connectors. Furthermore, org.camunda.connect.Connectors.getConnector(String connectorId) can be used to explicity retrieve the connector by a specific provider.