3 simple ways to create connectors for the Bonita Platform

Nicolas Chabanoles — Wed, 10 Jun 2020 15:20:38 +0000

When using the Bonita platform to develop an application or process, connectors are a means to interact with your information system (IS) to read or write data. A connector is merely a piece of Java code that connects to the IS to execute an operation (read or write).

Bonita comes natively with 50+ connectors to fit the most generic use cases. Among the most frequently used connector family, you have the REST connectors, e-mail connector, and the database connectors (data source / JDBC). Chances are that you will find the connector you need directly from the provided library.

If that is not the case, no worries, the Bonita platform lets you define new connectors to meet your needs!

In this article, I will explain 3 simple ways to create a connector. But before we dive into the tutorial, I think it is important to introduce 2 notions: connector definition VS connector implementation.

Connector definition

A connector definition is a contract (described in an XML file) that the connector will fulfill, i.e. the list of input parameters with their type, the list of output parameters with their type, and the description of the UI to provide to the user so they can configure the connector from Bonita Studio.

For instance, a Slack connector definition may contain the following inputs.

Input 1

Name: channel
Type: Text
Widget: TextInput

Input 2

Name: message
Type: Text
Widget: TextArea (for long text)

Input 3

Name: slackServer
Type: URL
Widget: TextInput

And as output:

Name: responseCode
Type: Number

In this example, responseCode will provide a hint about whether the message has been sent or queued by the server.

Connector implementation

The connector implementation is the Java class that respects the connector definition and also extends the Java AbstractConnector class.

To simplify, it is a Java class with connect(), executeBusinessLogic(), and disconnect() methods that will be called in sequence by the Bonita platform.

If we continue with our Slack connector example, the connect() method will use the slackServer input parameter value to connect to the service. The executeBusinessLogic() method will use the other input parameters to compose the message and send it to the right channel.

In this article, we will see how to create both the definition and the implementation of a connector in Bonita.

Using Bonita Studio

The simplest way to create a connector (especially the definition) is to use Bonita Studio directly. It provides graphical wizards to build the definition.

Connector Definition

From the Development menu, select Connectors and New definition…

Create UI for connector definition

Note: you will also have the opportunity to translate the generated UI for your connector configuration. This allows developers to configure your connector in their language.

Once you have completed the definition, you can start using the connector in your process model. You do not need the implementation to model a process that will call your connector - but you will need the implementation when you execute the process.

It is very easy to forget an input or to misconfigure the UI widget at this stage. In my opinion, the best way to check that a connector definition is conceived properly is to use the connector in a process.

Select a connector to call on a human task

Configure the connector to send a Slack notification when a task is available

If you spot any mistakes you can edit the definition and make all the changes that seem relevant to you. And by doing this before implementing the connector, you save time on the implementation impacts.

Connector Implementation

Now that your definition is complete and you have quickly validated that it fits your needs by using it in a process, we can dive into the Java coding.

From the Development menu select Connectors and New implementation…

Select a connector definition to implement

Select the connector definition you want to create an implementation for (Slack in our example). Go through the wizard page by page and adapt the values to your situation or leave them as is. At the end of the wizard, you will be directed to the connector Java editor where you will implement the 3 Java methods that define the connector behavior.

Connector Implementation in Java

Once you have implemented the connector, you can run your process.

Note: How to create a SlackClient is out of scope of this article. You can find some good implementations on Maven Central.

Using your IDE

We are going to create a new project from a Maven archetype that will generate the project structure for both the connector definition and implementation.
I use IntelliJ IDEA, but you can do the same with your favorite IDE (e.g Eclipse, Visual Studio, etc).

You may have to add the Maven archetype the first time you will use it: New project > Maven > Create from archetype > Add Archetype...

Add Maven Archetype

The information you have to specify is:
GroupId: org.bonitasoft.archetypes
ArtifactId: bonita-connector-archetype
Version: 1.1.0

Next time you’ll just need to select the archetype from the list.

Make sure to specify the parameters required by the archetype:

Create a Kotlin project for your connector

className: SlackConnector (The Java class containing the business logic)
language: kotlin (possible values: java, groovy, kotlin)
bonitaVersion: 7.10.4 (any version of Bonita platform)

You now have a Maven project in your favorite IDE and are free to implement your connector and edit its definition from the generated files! For more information, you can refer to the Bonita documentation: https://documentation.bonitasoft.com/bonita/latest/connector-archetype

Using the CLI

If you usually use a terminal to create your projects, then you can use the Maven archetype directly from the command line.

mvn archetype:generate -DarchetypeGroupId=org.bonitasoft.archetypes -DarchetypeArtifactId=bonita-connector-archetype -DarchetypeVersion=1.1.0

You'll then have to interactively specify the properties of your project.

There is a comprehensive README.md file in the GitHub repository of the project for more information: https://github.com/bonitasoft/bonita-connector-archetype.

Now you have seen 3 simple ways to create connectors for the Bonita platform. I invite you to create your own and share them with the Bonita community here: https://community.bonitasoft.com/

DEV Community: Nicolas Chabanoles