How to add a new java connector in BonitaSoft?

This tutorial briefs the concept of connectors in BonitaSoft, also it shows step by step way to create your own java connector which will take some input and return some output after performing some business logic.

Prerequisites:You should have installed BonitaSoft Studio 5.5 or later, along with JDK-5 or later

Connector Concept: – Connectors in BonitaSoft is similar to the adapters in the web applications. Whenever business process wants to interact with outside world, connectors are used to do so.  Not to mention connectors in BonitaSoft behave in a similar way as Adapters in Savvion. For more details on connector/adapter concept, please go here (link of BPM adapter comes here). BonitaSoft has some of the inbuilt connectors which they have categorized as BonitaSoft, Database, Google, SAP, Social, Java, LDAP etc…  also a huge amount of community provided connectors are available which can be downloaded from the BonitaSoft community. This tutorial will only talk about the java connectors as I believe that everything can be achieved by a java class…lol

JAVA Connector Concept: – To create a java connector in BonitaSoft you will need to deal with 3 files –

1. JAVA file – This is the primary java class where all the business logic is performed, following are the things which you need to know about this class-

• It needs to extend the “ProcessConnector” class
• All the input to the connectors will have setter methods
• All the outputs will have the getters method
• validateValues() is a method which acts a validator, essentially you will validate your input variables and other exception influential part such as testing Database connection or testing network connection, For any erroneous condition you can throw an exception along with message, pity similar you do in user defined exception
• executeConnector()is method where all the business logic to be performed goes here.

2. XML file – Since BonitaSoft is build on the concept of GWT, it maintains an xml file to handle all configurations. So it creates an file too where all the detail such as input and output variables along with type is declaired.

3. Property file – It is a normal property file used the same way as we do in JAVA also locale can be set in this property file.

Apart from this if you need to use any other javalibrary/api, you can import them in the resources and use the same in connector.

(RELAX… you don’t need to worry about these files any more, as BonitaSoft 5.5 onwards BonitaSoft internally writes xml, property files for you and also it creates the basic class structure, which we watching soon)

Step by Step way to make Java Connector :-

To make the things simple I will make a java connector which will take 2 input values as input and return the summation of these two values

Step:-

1. Click on connectors -> new connector from top menu bar, a new pop opens in which you need to add following-

New Connector Widget

• Id – id of the connector
• Description
• Choose category as – java
• Name a class – by default it has the same as of id but obviously you can change it.
• In pages you will tell input parameter required by your connector and in outputs, the output returned by your connector to add the input variable.
•  click on create of page, a new pop up opens, where you will be filling  following –

Adding input Variables

i. Page Id – When you connector is created and ready to be configured, essentially in BonitaSoft this opens in a new widget/window, where you would be providing  the input and outputs , so this page id is nothing but the id of widge

ii. Pagetitle – the title of the widget, name it any thing

iii. Description

iv. Add fields, num1 and num2 in our case along with the way it should be displayed in widget, text in our case and the type.

v. In similar way output variable (note:- since this is the output and it is not the part of the widget, you can add it directly in connector creation window)

2. Once you done with above, BonitaSoft studio internally crates xml, property file along with skeleton of Java file and opens the java file in your studio all you need to do is write the logic and its done.

package com.constonline.connectors;

import java.util.List;
import java.util.ArrayList;

import org.ow2.bonita.connector.core.ConnectorError;
import org.ow2.bonita.connector.core.ProcessConnector;

public class Addition extends ProcessConnector {

    private java.lang.Long sum;
    // DO NOT REMOVE NOR RENAME THIS FIELD
    private java.lang.Long num2;
    // DO NOT REMOVE NOR RENAME THIS FIELD
    private java.lang.Long num1;

    @Override
    protected void executeConnector() throws Exception {
        // TODO Auto-generated method stub
        sum =this.num1+this.num2;

    }

    @Override
    protected List<ConnectorError> validateValues() {
        if (this.num1==0 || this.num2==0){
                ConnectorError connectorError = new ConnectorError("Values of num1&num2 cant be zero" ,new Exception ("num1:"+num1+"num2"+num2));
                        List<ConnectorError> list = new ArrayList<ConnectorError>();
                        list.add(connectorError);
                        return list;
        }else 

        return null;
    }

    /**
     * Getter for output argument 'sum'
     * DO NOT REMOVE NOR RENAME THIS GETTER, unless you also change the related entry in the XML descriptor file
     */
    public java.lang.Long getSum() {
        // TODO Add return value for the output here
        return sum;
    }

    /**
     * Setter for input argument 'num2'
     * DO NOT REMOVE NOR RENAME THIS SETTER, unless you also change the related entry in the XML descriptor file
     */
    public void setNum2(java.lang.Long num2) {
        this.num2 = num2;
    }

    /**
     * Setter for input argument 'num1'
     * DO NOT REMOVE NOR RENAME THIS SETTER, unless you also change the related entry in the XML descriptor file
     */
    public void setNum1(java.lang.Long num1) {
        this.num1 = num1;
    }

}

All in red is added in prewritten java file.

That’s it now you can test your connector –

1. Go to connector->test a connector->java type and click on the connector you created just now, a new widget opens, provide the inputs and click on evaluate, if you get the desired output your connector is working fine.

Test a Connector