Web service connector

Overview of the generic web service connector

The Bonita Studio includes a generic web service connector that leverages SOAP 1.2 protocol.

Generic configuration

  1. Go to Web services in the connectors list.

  2. SelectWeb Service Client.

  3. Click on Next

  4. Enter a name and description for the connector.

  5. Click on *Next.*

To format your entries according to SOAP specifications, go to SOAP!

See a working example of a web service connector in this tutorial.

This connector uses the StAX API. StAX libraries cannot be loaded in more than one classloader but must instead be placed in a single location where they can be called by all the items that use them.
When you configure a process that uses this connector, you must manage the configuration process dependencies.

Input

Input type Description Type

Target NS

Target NS (URL)

String

Service name

Name of web service

String

Port name

Web service port name

String

Request

Request entity

String

End point address

URL

String

Binding

Specify protocol and data format

String

Password

Password of user authorized to access

String

Service NS

Target namespace (URL)

String

Service name

Name of web service

String

Port name

Web service port name

String

End point address

URL

String

Binding

Specify protocol and data format

String

Output

Output type Description Type

Response

Result of execution

Source

Result

The connector will locate and execute the specific web service and return and output in the form of a Java object.

Tutorial

Learn how to use a Web Service connector to call a publicly available Web Service, store the answer and display the information.

The web service used in this example provides the capital of a given country.

  1. In the BDM, create a business object *Country* with the following attributes:

Name Type

id

STRING

capital

STRING

  1. Create the diagram (as shown in the example bellow)

web service process diagram

  1. Select the Pool > Data, click on the *Pool Variables tab*, add a process variable country (Text) and a Business variable countryBo (Country)

  2. Select the Pool > Execution, click on the *Contract tab*, and add a variable countryInput (Text) on the contract.

  3. Add an instantiation form: select the Pool > Execution, click on the *Instantiation form tab*, and click on the pencil on the right of the field Target form, it should open the UI designer. The idea here is to create a combo box which will propose some countries. The selected country will be passed to the contract.

    • Rename the form into countrySelection

    • Add a JSON data countries, with the following content:

      [{ "name": "France","code": "FRA"},{"name": "Switzerland","code": "CH"},{"name": "Finland","code": "FI"}]

    • Add a select widget, with the following parameters:

      • Availables values: countries

      • Displayed key: name

      • Returned key: code

      • Value: formInput.countryInput

    • Ensure in the preview that the combo box gives the possibility to select one of the countries, and we are done for the instantiation form.

  4. Go back on the country process variable, and set the countryInput as default value.

  5. Select the *No* flow, go on the *General tab* and set this flow as the Default flow.

  6. Select the *Yes* flow, go on the *General tab*. Check Use expression, and add the following script as the expression to use:

!countryDAO.findById(country, 0, 100).isEmpty()

  1. Select the *Retrieve already known capital task*, go on the *Execution tab* and click on *Operations*. Add the following operation:

    • Left operand: countryBo

    • Operation: takeValueOf

    • Right operand: A script retrieveCountry, with the following content:

countryDAO.findById(country, 0, 100).get(0)

  1. Select the *retrieveUnknownCapital* task, go on the *Execution tab* and click on *Connectors in*.

  2. Add a *WebService SOAP 1.2* connector to this task and configure it using the wizard.

  3. Enter the WDSL URL http://webservices.oorsprong.org/websamples.countryinfo/CountryInfoService.wso?WSDL, and click on the Introspect button, then leave the login info fields empty

  4. In the Request parameters window (for all editions), provide these settings:

    <?xml version="1.0" encoding="utf-8"?>
    <soap12:Envelope xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
      <soap12:Body>
        <CapitalCity xmlns="http://www.oorsprong.org/websamples.countryinfo">
          <sCountryISOCode>${country}</sCountryISOCode>
        </CapitalCity>
      </soap12:Body>
    </soap12:Envelope>

  1. In the Response configuration window, check the Returns body checkbox to use the response body in the output operations.

  2. In the Output operations window, keep only one output operation:

    • Left operand: countryBo

    • Operation: Java method -> setCapital

    • Right operand: A script parseCapital returning a String, with the following content

      import groovy.xml.XmlUtil

def reponseBody = new XmlSlurper().parseText(XmlUtil.serialize(responseDocumentBody.getDocumentElement()))
reponseBody.text()
To manipulate more complex XML documents, have a look to the Groovy XML processing documentation page.

And we are done for the connector configuration. If you want to test it from the wizard, replace ${country} by FRA in the envelope, and ensure that Paris is returned.

  1. Select the *Retrieve unknown capital* task, go on the *Execution tab*, click on *Operations* and add the following operation:

    • Left operand: countryBo

    • Operation: Use a java method -> setId

    • Right operand: country

  2. Select the *Display capital* task, go on the *Execution tab*, click on *Form* and click on the pencil to create the form of this task. The UI Designer should open. The idea here is to simply display the field capital of the business object used in the case (which has been created during the case or retrieved from the database). This business object is accessible in the context.

    • Create a *Javascript expression* variable named *api*, with the following content:

      return "../" + $data.context.countryBo_ref.link;

    • Create an *External API* variable named *country*, with the following api url:

{{api}}

  • Insert a text widget in the form, with the following text property:

Capital: {{country.capital}}

Rename the form into *Display capital*, save it, and we are done.

  1. We do not want to implement a case overview for this simple use case. Select the pool, go on the *Execution tab*, click on *Overview page* and select *No form*.

  2. Test the process, by following those steps:

    • Select the pool

    • Configure the actor mapping to the group "/acme"

    • Click on the "Run" button to install and enable the process and be redirected to the instantiation form

    • From the instantiation form in your browser, select a country and submit

    • The browser will be redirected to the Bonita User Application

    • A new task "Display Capital" should be available (refresh if not), click on it

    • The capital should appear on its associated form