Bonita connector archetype

<?xml version="1.0" encoding="UTF-8"?>
<definition:ConnectorDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:definition="http://www.bonitasoft.org/ns/connector/definition/6.1">
    <id>myConnector</id> <!-- Id of the definition -->
    <version>1.0.0</version> <!-- Version of the definition -->
    <icon>connector.png</icon> <!-- The icon used in the Studio for this definition -->
    <category icon="connector.png" id="Custom"/> <!-- The category of this definition, used in the Studio (e.g: http, script ...) -->

    <!-- Connector inputs -->
    <input mandatory="true" name="defaultInput" type="java.lang.String"/>

    <!-- Connector outputs -->
    <output name="defaultOutput" type="java.lang.String"/>

    <!--
       Pages and widgets to use the connector in the Bonita Studio.
       - Each widget must be bound to an input
       - Page titles must be defined in the properties files
       - Widget labels must be defined in the properties files
       - Page and widget descriptions can be defined in the properties files (optional)
    -->
    <page id="defaultPage">
        <widget xsi:type="definition:Text" id="defaultInputWidget" inputName="defaultInput"/>
    </page>

</definition:ConnectorDefinition>

./mvnw clean install

GET /api/people/?search=yoda

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "Yoda",
            "height": "66",
            "mass": "17",
            "hair_color": "white",
            "skin_color": "green",
            "eye_color": "brown",
            "birth_year": "896BBY",
            "gender": "male"
            ...
        }
    ]
}

package com.company.connector.model

import com.fasterxml.jackson.annotation.JsonIgnoreProperties

@JsonIgnoreProperties(ignoreUnknown = true)
class Person implements Serializable {

    String name

    String gender

    String height

    String homeworld
}

package com.company.connector.model

import com.fasterxml.jackson.annotation.JsonIgnoreProperties
import com.fasterxml.jackson.annotation.JsonProperty

@JsonIgnoreProperties(ignoreUnknown = true)
class PersonResponse implements Serializable {

    @JsonProperty("results")
    List<Person> persons = []
}

package com.company.connector

import com.company.connector.model.PersonResponse
import retrofit2.Call
import retrofit2.http.GET
import retrofit2.http.Headers
import retrofit2.http.Query

interface StarWarsService {

    @Headers("Accept: application/json")
    @GET("api/people")
    def Call<PersonResponse> person(@Query("search") String name)
}

    def static final NAME_INPUT = "name"
    def static final URL_INPUT = "url"

    @Override
    def void validateInputParameters() throws ConnectorValidationException {
        checkMandatoryStringInput(NAME_INPUT)
        checkMandatoryStringInput(URL_INPUT)
    }

    def checkMandatoryStringInput(inputName) throws ConnectorValidationException {
        def value = getInputParameter(inputName)
        if (value in String) {
            if (!value) {
                throw new ConnectorValidationException(this, "Mandatory parameter '$inputName' is missing.")
            }
        } else {
            throw new ConnectorValidationException(this, "'$inputName' parameter must be a String")
        }
    }

    def should_throw_exception_if_mandatory_input_is_missing() {
        given: 'Connector with missing input'
        def connector = new ConnectorStarWars()

        when: 'Validating inputs'
        connector.validateInputParameters()

        then: 'ConnectorValidationException is thrown'
        thrown ConnectorValidationException
    }

    def should_throw_exception_if_mandatory_input_is_empty() {
        given: 'A connector without an empty input'
        def connector = new ConnectorStarWars()
        connector.setInputParameters([(ConnectorStarWars.NAME_INPUT):''])

        when: 'Validating inputs'
        connector.validateInputParameters()

        then: 'ConnectorValidationException is thrown'
        thrown ConnectorValidationException
    }

    def should_throw_exception_if_mandatory_input_is_not_a_string() {
        given: 'A connector without an integer input'
        def connector = new ConnectorStarWars()
        connector.setInputParameters([(ConnectorStarWars.NAME_INPUT):38])

        when: 'Validating inputs'
        connector.validateInputParameters()

        then: 'ConnectorValidationException is thrown'
        thrown ConnectorValidationException
    }

def StarWarsService service

@Override
def void connect() throws ConnectorException {
    def httpClient = createHttpClient(new HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BASIC))
    service = createService(httpClient, getInputParameter(URL_INPUT))
}

def static OkHttpClient createHttpClient(Interceptor... interceptors) {
    def clientBuilder = new OkHttpClient.Builder()
    if (interceptors) {
        interceptors.each { clientBuilder.interceptors().add(it) }
    }
    clientBuilder.build()
}

def static StarWarsService createService(OkHttpClient client, String baseUrl) {
    new Retrofit.Builder()
            .client(client)
            .addConverterFactory(JacksonConverterFactory.create())
            .baseUrl(baseUrl)
            .build()
            .create(StarWarsService.class)
}

package com.company.connector

import com.company.connector.model.PersonResponse
import okhttp3.logging.HttpLoggingInterceptor
import retrofit2.Response
import spock.lang.Specification

class StarWarsServiceTest extends Specification {

    /**
     * Service integration test - internet required
     */
    def should_retrieve_luke_data_using_retrofit() {
        given: 'A service'
        def httpClient = ConnectorStarWars.createHttpClient(new HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY))
        def service = ConnectorStarWars.createService(httpClient, "http://swapi.dev/")

        when: 'Searching for luke'
        def call = service.person("Luke")
        def Response<PersonResponse> response = call.execute()

        then: 'Should contain Luke data'
        assert response.isSuccessful() == true
        assert response.body.persons.size() == 1
        assert response.body.persons[0].name == "Luke Skywalker"
    }
}

def static final PERSON_OUTPUT = "person"

@Override
def void executeBusinessLogic() throws ConnectorException {
    def name = getInputParameter(NAME_INPUT)
    log.info "$NAME_INPUT : $name"
    // Retrieve the retrofit service created during the connect phase, call the 'person' endpoint with the name parameter
    def response = getService().person(name).execute()
    if (response.isSuccessful()) {
        def persons = response.body.getPersons()
        if (!persons.isEmpty()) {
            def person = persons[0]
            setOutputParameter(PERSON_OUTPUT, person)
        } else {
            throw new ConnectorException("$name not found")
        }
    } else {
        throw new ConnectorException(response.message())
    }
}

def server
def connector

def setup() {
    server = new MockWebServer()
    def url = server.url("/")
    def baseUrl = "http://${url.host}:${url.port}"

    def httpClient = ConnectorStarWars.createHttpClient(new HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY))
    def service = ConnectorStarWars.createService(httpClient, baseUrl)

    connector = new ConnectorStarWars()
    connector.service = service
}

def cleanup() {
    server.shutdown();
}

/**
 * Connector unit test - no internet required
 */
def should_fetch_person() {
    given: 'A person name'
    def name = 'Luke'
    and: 'A related person JSON response'
    def body = """
        {"results": [
            {
                "name":"$name Skywalker",
                "height":"172",
                "mass":"77",
                "hair_color":"blond",
                "skin_color":"fair",
                "eye_color":"blue",
                "birth_year":"19BBY",
                "gender":"male",
                "homeworld":"http://swapi.dev/api/planets/1/"
            }
        ]}
    """
    server.enqueue(new MockResponse().setBody(body))

    when: 'Executing connector'
    connector.setInputParameters(['name': name])
    connector.executeBusinessLogic()

    then: 'Connector output should contain the person data'
    def outputParameters = connector.outputParameters
    outputParameters.size() == 1

    def person = outputParameters.get(ConnectorStarWars.PERSON_OUTPUT)
    person instanceof Person
    person.name == "Luke Skywalker"
}

/**
 * Connector unit test - no internet required
 */
def should_get_unknown_person() {
    given: 'An API server'
    String body = "{\"results\":[]}"
    server.enqueue(new MockResponse().setBody(body))

    when: 'Executing business logic'
    def name = 'Luke'
    connector.setInputParameters(['name': name])
    connector.executeBusinessLogic()

    then: 'Connector should throw exception'
    def e = thrown(ConnectorException)
    e.getMessage() == "$name not found"
}

/**
 * Connector unit test - no internet required
 */
def should_handle_server_error() {
    given: 'An API server'
    server.enqueue(new MockResponse().setResponseCode(500))

    when: 'Executing business logic'
    def name = 'Luke'
    connector.setInputParameters(['name': name])
    connector.executeBusinessLogic()

    then: 'Connector should throw exception'
    def e = thrown(ConnectorException)
    e.getMessage() == "Server Error"
}