Consuming Web Services

Consuming Web Services

Introduction

Purpose

This document describes how you use a web service consumer in a workspace workflow in Comflow.

There is a practical example on how to use a web service consumer in the CVS project CAExamples in Comflow Studio. That example functions as a complement to this document. For more information, see the Related Information section.

Who should read this document?

This document is intended for developers who work for a Corzia partner or a customer, and who use Comflow for development.

The document assumes that the reader has a good knowledge in the concept of web services and how web service operations are defined in Web Service Description Language (WSDL) documents. The reader also needs to be well-acquainted with how to develop workspaces in Comflow.

Presentation of content

Consuming web services

Limitations

There are some limitations to how web service consumers can be used in Comflow workflows:

• There is no support for managing parameters that are structured hierarchically. This means that you cannot use input parameters (already generated parameters that will be used as input data by the web service consumer) that have the same name but different location in a hierarchy. It also means that you cannot use hierarchically structured output parameters (response data that is generated by the invoked web service operation).
• The web service consumer can only be used with web service producers that are publishing web services in the RPC literal or document literal format.

Also note that though web service consumers are supported by Comflow, there is not yet any dedicated Comflow plug-in for creating the web services themselves. We recommend you to look at Eclipse Web Tools Platform (WTP) project (http://www.eclipse.org/webtools).

About web service consumer

A web service consumer is a component used to locate a web service and to invoke an operation that the web service provides. A WSDL document is an XLM-based language that describes the web service. It provides information on where the web service is located, the available operations and how they are invoked.

In Comflow, a web service consumer can be inserted in a workspace workflow and the result generated by the invoked web service operation can be used, for display or further processing, later in the workflow.

About input parameters

If input parameters (that exist in the data instance) are needed by the web service operation that is invoked, you need to create a map for them. In the map, create one variable for each input parameter. When mapping, it is important that you name each input parameter according to its name in the WSDL document.

Example: A web service operation that calculates the currency rate might need from currency and to currency as input parameters.

About output parameters

Whenever the web service consumer has been activated and performed its job, the response (the output parameters) is automatically stored in mapdata as virtual variables. The variables will automatically be named according to their name in the WSDL document.

Note that in order to manage the result and use it in the next step in the workflow, you might need to map the response variables.

Adding a web service consumer – Process

The outline below is an example flow of how to enable a web service consumer.

Note that the activities do not necessarily have to be carried out in that specific sequence. ‘Complete the workflow’ refers to all sorts of normal work when developing workspace workflows, such as adding actions, execution points and transitions.

WSDL document – Example

When using a web service consumer in Comflow, you need to be able to interpret the corresponding WSDL document since the name definitions etc in the document is used when configuring the web service consumer in the workspace workflow.

In the WSDL document example below, the definitions that are used when configuring the web service consumer are highlighted.

WSDL document for calculating currency rate

Add and configure a web service consumer

Use this task to add a web service consumer to a workspace workflow, and to configure the consumer.

Before starting

• An available web service must exist.
• An available WSDL document referring to the web service must exist. You must be able to interpret the document.
• A workspace workflow that will use the web service consumer must exist.

Step list

1. Open the project in the Package Explorer view.
2. Open the Workspace folder.
3. Identify the workspace, and open it by double-clicking on it.

Add a web service consumer to the workflow

1. In the Editor, select the web service icon () on the toolbar, and click in the workspace where you want the web service to be inserted.

Configure the web service consumer

1. Open Designer Properties > Logic tab.
2. Specify the URI that represents the location of the WSDL document on the Internet.
3. Specify the name of the web service.

The name of the service can be found in the WSDL document, according to below:

1. Specify the name of the port that is used.

The name of the port can be found in the WSDL document, according to below:

1. Specify the name of the web service operation that you want the consumer to invoke.

Note that though a web service can provide several operations, it is only possible to invoke one operation per web service consumer in a workflow. The name of the operation can be found in the WSDL document, according to below.

1. If you want the complete response from the invoked operation to be included in the mapdata, set the Include Response Tree to True.

The complete response will be stored as a long string in the variable SOAPOPERATIONRESPONSETREE.

This is an example of a response tree in a WSDL document:

If you select to include the complete response in the mapdata, it will be stored as a string in the variable SOAPOPERATIONRESPONSETREE. According to the example above, the string SOAPOPERATIOONRESPONSETREE will look as follows:

1. Click Save.

Related information

The table below lists documents or resources with useful and related information.