This documentation is about a version that is out of support, here is the latest documentation version.

How about downloading a newer, supported version?

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





  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()
  7. 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)
  8. Select the *retrieveUnknownCapital* task, go on the *Execution tab* and click on *Connectors in*.

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

  10. In the Connection parameters window:

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

       <?xml version="1.0" encoding="utf-8"?>
    <soap12:Envelope xmlns:soap12="">
        <CapitalCity xmlns="">
  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 ```groovy import org.codehaus.groovy.ast.stmt.ContinueStatement import org.w3c.dom.NodeList


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.

16. 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

17. 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 "../" + $;
  • Create an *External API* variable named *country*, with the following api url:

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

    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 user perspective in the Portal

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

    • The capital should appear on its associated form