Altova MapForce 2023 Enterprise Edition

When you need to call a Web service with URL parameters, the parameters must be defined in the Web Service Call Settings dialog box. This dialog box also lets you configure the Web service request with custom headers. You can configure the parameter values to be mappable (supplied by the mapping) or fixed (defined on the dialog box).

 

To define Web service parameters, take the following steps:

 

1.Double-click the title bar of the Web service component in the mapping or right-click it and select Properties. The Web Service Call Settings dialog box opens.

mf_ws_03

2.Under Service Definition, select Manual. You can enter the parameters manually or automatically (by importing them from an existing URL or from a WADL file). The imported parameters become available in the Parameters table (see subsection below), where you can further modify them if required.

3.Use the Add Parameter ( ic_paramadd ) and Delete Parameter ( ic_paramdel ) buttons, as required.

 

Parameters

The subsections below summarize the available parameters in the Web Service Call Settings dialog.

 

 

Example 1: Header and template parameters

The Web service illustrated below retrieves a product by its identifier (id) using the HTTP GET method. The URL of the Web service specifies the id parameter in the curly brackets. Notice that the id parameter exists in the Parameters table and has the style Template. It is also mappable: this causes the parameter to appear on the mapping as a structure node to which you can connect the actual value of id (which could be, for example, taken from a database, a file, or a constant). At mapping execution runtime, this parameter would be replaced with the actual value; so, if the value is "1", the URL becomes http://example.org/api/products/1 .

 

To supply a constant id value instead of a value from the mapping, clear the check box "Mappable" and enter the value in the "Fixed value" column.

mf_ws_03

The parameters Accept and Accept-Charset have the Header style. These parameters are used to call the Web service with custom request headers. There are two ways to supply the header value:

 

Leave the option Mappable checked and supply the custom header value from the mapping, or

Clear the option Mappable and enter the value directly in the "Fixed value" column.

 

Example 2: Matrix parameters

The Web service illustrated below retrieves a list of products that match the color and size supplied as arguments. The style of the parameters is "Matrix", so they are defined both as placeholders inside the URL and in the mapping table. Notice that the parameters are mappable and the "Repeating" option is checked. This means that their value will be read from some sequence of values on the mapping (for example, a list of rows inside a text file, an XML node, or a database column) and supplied to the Web service at runtime. Thus, a URL such as the one below would become http://example.org/api/products/;color=red;color=blue;size=big;size=small, provided that the mapping supplies red and blue as colors, and big and small as size.

mf_ws_04

If you need the URL to be http://example.org/api/products;color=red,blue;size=big,small, do the following:

 

1.Enter the URL as http://example.org/api/products;color={color};size={size}

2.In the Parameters table, change the parameter style to Matrix.

 

If you need the URL to be http://example.org/api/products?color=red,blue&size=big,small, do the following:

 

1.Enter the URL as http://example.org/api/products?color={color}&size={size}

2.In the Parameters table, change the parameter style to Matrix.

 

Example 3: Query parameters

The Web service illustrated below also retrieves a list of products that match the color and size supplied as arguments, this time using the style "Query". For this style, it is not necessary to define the parameters as placeholders in the URL, so they are defined only in the "Parameters" table. In this example, let's assume that the parameter values are fixed and must not be supplied from the mapping. To achieve this, the parameter values were entered under "Fixed Values", and the "Mappable" option is unchecked. Thus, at mapping runtime, the URL below would become http://example.org/api/products?color=red&size=big.

mf_ws_05

© 2016-2022 Altova GmbH