Integrating Synchronous Web Services

Web Services provide a standardized way to call remote services via HTTP communication. Infinity Process Platform allows you to use Web Services as an application type for applications invoked by arbitrary activities in a process. Data can be passed to and retrieved from Web Services as parameters via the access point concept. For the remainder of this section, it is assumed that you are familiar with Web Service Technology and the relevant specifications (especially WSDL 1.1).

This section is exclusively dealing with synchronous Web Services.

Specifying Web Service Applications

A Web Service Application is specified in the application properties dialog by means of a specific panel.


Figure: Web Service Application

Details of the different parameters specified in this dialog are described in the following sections.

Operation-specific parameters

All parameters needed to specify a certain Web Service operation and its call parameters are specified on the entry field Operation. The value in this entry will determine which fields and contents are displayed in the dialog.


Figure: Web Service Application with Operation-specific Parameters

WSDL URL

The location of the WSDL specification containing a description of the Web Service to be invoked. Reloading the WSDL specification or loading a different WSDL specification will invalidate any chosen service. The WSDL URL can be specified in the form of any URL including file URLs. Furthermore, you can load a WSDL file as a resource from the application classpath by specifying a WSDL URL without any protocol. For example you would specify a URL com/bpm/example/ExampleService.wsdl if you want to load a file ExampleService.wsdl located in a package com/bpm/example within the application classpath.

Note: The WSDL URL is also used at runtime to prepare Web Service invocations. You need to ensure that this URL is available also from your runtime application server environment.

Service

Selects the service to be invoked from the services listed in the previously loaded WSDL specification.

Modifying the service selection will invalidate any selected port.

Port

Selects the port to be invoked from the ports provided by the previously selected service.

Modifying the port selection will invalidate any selected operation.

According to the 1 to 1 relationship between ports and port bindings, selecting a port will implicitly select a port binding as well.

Operation

Selects the operation to be invoked from all operations provided by the previously selected port.

Modifying the operation will imply changes to the style, use and parameter configuration as well.

Due to the 1 to 1 relationship between operation bindings and operations, selecting an operation will implicitly select an operation binding as well.

Style

Indicates the encoding style used for the chosen operation.

Use

Indicates the message used for the chosen operation.

Include WS-Addressing Endpoint Reference

This checkbox allows to specify that at runtime a WS-Addressing Endpoint Reference will be included into the request message. Using WS-Addressing allows to specify the invoked SOAP endpoint. If this feature is selected, a special access point named WS-Addressing Endpoint Reference is generated for the activity. By creating data mappings to this access point you can specify the authentication credentials to be set at runtime.

Authentication

This checkbox allows to specify whether at runtime any standard caller authentication information is included into the request message. Currently the following authentication mechanisms are supported:

Authentication
Figure: Authentication

If this feature is selected, a special access point named Authentication is generated for the activity. By creating data mappings to this access point you can specify the authentication credentials to be set at runtime.

Using HTTP Basic Authentication

In case you define a Web service application that uses http basic authentication and pass it as In-data mapping to an application activity, an access point Authentication is provided in the application context, as described above.

Access Point Authentication
Figure: An Access Point Authentication is provided.

To pass in the credentials you can use the Access Point Path to browse to the setters for the individual values (e.g. setUsername(String), setPassword(String)).


Figure: Choose a Setter Class as Access Point Path


Figure: The resulting Application Context

Parameter Handling

Web Service invocation parameters basically map to message parts. The tab Parts of the Web Service Application properties panel lists all message parts for the currently selected operation.


Figure: Parameter Handling

The list contains the name of the part and its XML type. For every message part the table also contains a checkbox Mapped specifying whether the part should be exposed as a mapped Java type or in the form of native XML.

If a message part is marked to be mapped, a type mapping has to be specified on the tab Mappings/Templates. If the underlying toolkit finds a default mapping for the XML type of a message part (e.g. in the case of primitive types), the checkbox Mapped is automatically checked and the default mapping is added. Otherwise the default value is unchecked.

Specifying Type Mappings and Message Part Templates

Select Web Service Application > Parts to specify the way message parts are exposed in more detail. For every message part either a Type Mapping (for message parts that have a Java type mapping) or an XML template (for parts exposed as an XML access point) can be specified.


Figure: Type Mappings

Java Bean Type Mappings

Arbitrary XML types can be mapped to appropriate Java Beans. The type to be mapped can either be entered in text form or selected from the loaded classes via the class browser. Default mappings are displayed in the table where available. Like any other type mapping, these defaults can be modified by the modeler if necessary.

For every type-mapped message part an access point of the corresponding Java type is created for the application. Based on this access point you can model the desired runtime data flow by defining data mappings to and from workflow data. At runtime, the XML part will be transparently converted to the mapped Java type. If the conversion from a XML message part to a Java object fails because of incompatible data structures, activity execution will be interrupted and audit trial logs describing the problem will be written.

Template-Based IN Parameters

Arbitrary XML IN Parts can be constructed with a template mechanism. For any IN Part that is not mapped to a Java type, a template of the Part's XML fragment can be specified in the Template entry field.

To specify the template directly at modeling time, add the XML template to the field Default Value in the table XML Templates. This is most easily done by opening the context menu Edit on the corresponding field and typing or pasting the XML template into the displayed dialog.


Figure: Passing a XML Template

If you prefer to set the template value at runtime you can do so by modeling an In-data mapping with empty access path to the corresponding XML access point.

At runtime, this template XML is used to create the actual Part value. Before it is passed to a Web Service, the template XML is subjected to all In-data mappings modeled for the XML Part's access point. This allows you to set the node values of the template XML via modifying XPath statements.

An example for this is given in the picture below.


Figure: Data Mapping for Setting a XML Template at Runtime

The data mappings defined in this example will do the following:

Hint: Please note that the declaring top-level element of an XML Part must not be included in the access path used.

Example: You would use the XPath expression address/city to access the node city in an XML Part of the form:

<in6 xmlns="http://echo.embedded.wfxml.utils.hydra.carnot.ag">
<address>
<city>Frankfurt</city>
<country>Germany</country>
<postcode>60598</postcode>
</address>
</in6>

Structured Data as Input and Output

Infinity supports using Structured Data as input and output in the Web Service Applications. In case the Web Service has structured types defined that exactly match parts of the input or output message (having same name and same namespace), an additional access point will be created, so that structured data (with that structured type assigned) can be used as input or output by the Web Service call.

Runtime Behavior

The WSDL specification chosen from the Web Service Application panel is stored by reference - not by value - with the corresponding model element. Hence, this WSDL resource has to be available to the Infinity Process Platform runtime at process execution time. Failing Web Service invocations will be treated like failing J2EE Session Bean invocations, causing the activity thread to be interrupted at the invoking activity.

Most probable sources of errors are:

Generating Classes

You have the option to automatically generate classes for the wrapper elements. A button Generate classes is provided in the Parts section that allows to generate classes based on the currently selected wsdl document. All the classes needed to invoke the service, including the WS client stubs are created. The generated stubs are JAX-WS 2.1 compatible.


Figure: Click to generate classes.

The Java source classes are created in the first Java source folder of the project containing the model. The parts are correspondingly mapped to the newly generated classes.

The following picture shows the property page entries after generating the classes:


Figure: Property Page with Generated Classes.

The parts are automatically mapped to the generated classes as shown in the following figure:


Figure: Mapped Parts

The generator creates annotated classes for all elements in the wsdl file in the current project:


Figure: Structure with Annotated Classes.

Configuring Retry Mechanism for Synchronous Application

The configurable retry mechanism provides the facility to retry an operation in case the target service is temporarily unavailable.

For more information, please refer to Retry Mechanism of Non-interactive Applications section of the Applications Concept chapter.

If you enable the Retry functionality for a Synchronous Web Service application, you have to define the number of retries and the time between retries in seconds. Note that the maximum number of retries is 10 and the maximum time between retries is restricted to 60 seconds. Additionally you can enable the retry to be performed on application side and thus disable a retry on engine side.


An application with an enabled retry functionality will retry for the defined number of times with a pause of the defined number of seconds, until it succeeds. If the application still fails after the defined number or time, it will no longer retry.