Parameters
If you call a Web service with URL parameters, you must define the parameters in the Parameters section of the Web Service Call Settings dialog box (screenshot below). This dialog box also enables you to configure the Web service request with custom headers.
As an alternative to manual definition, you can also fill in the Web service's parameters automatically, by importing them from an existing URL or from a WADL file.
Use the Add Parameter ( 
) and Delete Parameter ( 
) buttons to manage parameters.
The available settings are described below.
Name | Specifies the name of a URL parameter. The parameter name must be unique and may consist of alphanumeric characters, periods, hyphens, and underscores. No spaces are allowed in the parameter name. Depending on the parameter style, other characters can also be allowed. If the name is invalid, its cell will be highlighted in red.
|
Specifies the syntax (style) of a URL parameter.
•Use the Header style to add a parameter to the HTTP header when calling the Web service. For example, adding a parameter Accept with value text/xml is equivalent to specifying the Accept: text/xml header, which informs the Web server that MapForce expects the response to be in XML format. For more information about HTTP headers, see the Message Headers Specification. •Use the Query style for URL parameters that define key-value pairs using the ?key=value&key=value format (e.g., http://example.org/api/products?sort=asc&category=1&page=1). Allowed characters are: ASCII alphanumeric, Unicode chars, -._~ /?:@!$'()*;[], space. The following characters are not allowed: =&#. •Use the Template style for URL parameters enclosed within curly braces (e.g., http://example.org/api/products/{id}). For such parameters, MapForce escapes the values according to the RFC 6570 rules. •Use the Matrix style for URL parameters that define key-value pairs in the ;key=value;key=value; format (e.g., http://example.org/api/products;sort=asc;category=1;page=1;). To use Boolean matrix parameters, set the style to Matrix and the type to boolean. •Select Body to send an application/x-www-form-urlencoded request structure to an HTTP API (the request method must be POST). To find out more about the application/x-www-form-urlencoded format, see the URL Specification. Allowed characters are: ASCII alphanumeric, Unicode chars, -._~!$'()*+,;:@%/?#[], space. The following characters are not allowed: =&.
| |
Type | Specifies the data type of the parameter (string, integer, date, etc). This can be any XML Schema type. Note that a value that is not a string is converted to a string when a Web service call takes place. Setting a type is meaningful in the following case: You want MapForce to show conversion error messages when you attempt to call a Web service with wrong values.
|
Mappable | Select this check box if you want to pass values to this parameter from the mapping. This option is mutually exclusive with the Fixed Value option.
|
Fixed value | Specifies the value of the parameter. Applicable only if the parameter has a constant value. Not applicable if the parameter is mappable (see previous option).
|
Required | Select this check box if the parameter is required by the Web service. For parameters that are required and also mappable, MapForce enforces validation checks: An error message is displayed if the parameter does not have a value.
|
Repeating | Specifies whether the parameter is single-valued or may have multiple values. This setting is applicable only for mappable parameters. This option enables you to pass multiple values in the same Web service call by means of a single parameter. When you select the check box, you can connect a sequence of values to the parameter structure node in the mapping. MapForce will then handle the sequence of values depending on the style of the parameter:
•For Template parameters, the values will be supplied to the Web service as comma-separated (e.g., http://example.org/api/products/1,2,3). •For Query parameters, the parameter name will be repeated for each value (e.g., http://example.org/api/products?color=red&color=green&color=blue). •If the style is Matrix, multiple values will be separated by comma (e.g., http://example.org/api/products;color=red;color=green;color=blue;size=big;size=small;). •If the style is Header, the HTTP header will be repeated for each value.
|
Description | Specifies the optional description of the parameter. If the parameter is mappable, the description entered here appears in the mapping component as an annotation next to the mapping item.
|
Examples
This subsection describes some examples with various parameter configurations.
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 curly braces. 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 in the mapping as a 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 runtime, this parameter would be replaced with the actual value. For example, if the value is 1, the URL will become http://example.org/api/products/1.
To supply a constant id value instead of the value from the mapping, clear the Mappable check box and enter the value in the Fixed value column.
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 in the mapping (e.g., 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 will become http://example.org/api/products/;color=red;color=blue;size=big;size=small if the mapping supplies red and blue as colors, and big and small as sizes.
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 Query style. 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 have been entered under the Fixed Values column, and the Mappable option is unchecked. Thus, at mapping runtime, the URL below will become http://example.org/api/products?color=red&size=big.
