Web service connector 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:

      • Available 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