Web Service Calls
Generic (not WSDL-style) Web services include a large category of Web services that follow or partially follow an architectural style referred to as "REST" (and are typically called "RESTful", or REST-style Web services). Generic HTTP Web services typically carry custom request or response structures in the message body part. MapForce supports the following kinds of request or response bodies: JSON, XML, Protocol Buffers, and unstructured bodies carrying custom MIME types. Therefore, from a MapForce perspective, the prerequisites to call a Web service depend on the type of the request:
•In case of XML or JSON requests or responses, MapForce needs the request or response structure as a JSON, XML, or DTD schema. MapForce will also accept as structure an XML file with a valid schema reference. The structure of the Web service could be published by the service provider as XML or JSON schema, or through a formal language such as WADL, or even be a human-readable specification. If you already have the XML or JSON schema of the request/response, you will need the least amount of effort to create the Web service call. If you have the Web service definition as a WADL file, you can import it from the WADL file, and make any potential adjustments manually. Note, however, that WADL provides no standard way to define JSON structures, only XML structures. Finally, if you have a sample XML or JSON instance file but don't have a schema file, you can either create or generate the schema with XMLSpy (https://www.altova.com/xmlspy.html). If necessary, XMLSpy can also convert your instance file from XML to JSON, or vice versa.
•In case of Protocol Buffers requests or responses, you need the .proto file that describes the Protocol Buffers binary file. In this scenario, the body of the Web service can be mapped to or from a Protocol Buffers component. For more information, see Example: Read Data from Protocol Buffers and Example: Write Data to Protocol Buffers.
•You can also call Web services where the request or response structure is flexible and not tied to a particular schema. For such cases, you can use MapForce built-in mime functions to either create the raw message body sent to the Web service (the MIME entity) or process from the mapping the MIME entity returned by the Web service.
Adding a call to a generic Web service
1.On the Insert menu, click Web Service Function. (Alternatively, click the Insert Web service function 
toolbar button).
2.Under Service definition, click Manual.
3.Optionally, if you have the WADL file describing the service, click Import from WADL file and select the file, see also Importing Web Service Information from WADL.
4.Select the HTTP request method that MapForce should use to call the Web service. You can either select a value from the existing list, or type the name of the request method. The HTTP method names are case-sensitive.
5.Do one of the following:
a.Enter the URL of the Web service in the URL text box. In this approach, you can optionally turn specific parts of the URL into parameters and supply them from the main mapping. For URLs defined this way, note the following:
i.If you are calling a Web service with "template" or "matrix" style parameters, enclose the parameters within curly braces, for example: http://example.org/api/products/{id}. Then define the actual settings of each parameter in the "Parameters" table. At runtime, MapForce replaces the placeholders in curly braces with the actual parameter values and produces the final URL.
ii.If you are calling a Web service with "query" URL parameters (for example, http://example.org/api/products?sort=asc&category=1&page=1), do not enter the query part in the URL text box. Instead, define the parameters only in the "Parameters" table, and make sure to designate them as "Query"-style parameters.
iii.For examples, see Defining Web Service Parameters.
b.If you would like to supply the full URL of the Web service from the main mapping (or perhaps as parameter to the mapping), select the Dynamic URL (supplied by mapping) check box. This disables the URL text box and in this case you must create the full URL of the Web service (including any URL parameters) from the main mapping and connect it to the respective input that appears on the Web service component. Note that with this approach it is no longer meaningful to specify any parameters in the "Parameters" table, except for "Header"-style parameters. If you attempt to do this, a dialog box will warn you to this effect.
Dynamic URLs With either of the two approaches described above (fully or partially dynamic URLs), you can flexibly adjust the URL based on your needs. For example, you could run the mapping with a specific URL during development and use a different URL in production, without modifying the mapping. A URL like https://{host}/some/path/to/service would make this possible, assuming that the host name is the only difference between the production and testing URLs, and you supply it as a parameter to the mapping. Note that partially dynamic URLs enforce stricter validation, since only the designated URL parts are replaced with mappable or runtime values.
With fully dynamic URLs, the entire URL is mappable and you have complete control over it; the only requirement is that the URL must begin with http:// or https:// and it must be a valid URI. Dynamic URLs also make it possible to supply the URL returned from a Web service call as input to another component which may call the same (or some other) Web service. |
6.Optionally, under Timeout, enter a period in seconds after which the connection should time out if the server is not responding.
7.If the HTTP method requires or returns a body part (such as XML, JSON, and others), click the Edit button under Structure and browse for the schema of the body part. For more information, see Defining the Request Structure and Defining the Response Structure.
8.Under Parameters, define the parameters of the Web service. Optionally, click Import from URL to import the parameters from a sample URL of the Web service and populate the "Parameters" table automatically, as shown in Importing Web Service Parameters from URL. After importing parameters from a URL, you can modify the contents of the "Parameters" table if necessary.
| Note: | To specify custom request headers, add a parameter with style "Header", where the parameter name corresponds to the header name, and the parameter value corresponds to the header value. Furthermore, if you need to provide the value of the request header from the mapping itself, set the parameter type to "Mappable". For further information, see Defining Web Service Parameters. |
9.If the Web service requires basic HTTP authentication, OAuth 2.0 authorization, or certificate-based security, click the Edit button under HTTP Security Settings and fill in the required fields, see also Setting HTTP Security.
After you click OK, a new Web service component is added to the mapping area. For example, the mapping below calls a Web service in order to retrieve a product by its ID using a GET request. In this example, the ID supplied in the HTTP request has the constant value "2". However, it could also be a parameter to the mapping, or be supplied by any component supported by MapForce. In addition to the id parameter, the request contains the header Accept: text/json. You can set the request headers by means of "header" parameters, as shown in Defining Web Service Parameters.
Notice that the Web service component consists of two parts: Request and Response. The Request part enables you to supply data from the mapping to the Web service, while the Response part enables you to access the data returned by the Web service and map it to other formats. The structure of the request and response depends on the parameters, as well as the request or response structure you have defined by clicking the 
button. In the Web service call above, the structure of the request body is not set, while the structure of the response body is set as JSON—which makes it possible to map the result of the Web service to an actual JSON file.
To call the Web service with request parameters (if applicable), draw mapping connections between any component supported by MapForce (for example, an XML or JSON file) and the Request part. Likewise, to map data returned by the Web service to another format, draw mapping connections between the Response part and any other component type supported by MapForce. If you are new to MapForce and need instructions about drawing mapping connections, see Working with Connections.
The response headers returned by the Web service are also mappable, if they are additional headers (the ones which do not begin with "Content"). The header values are available on the Web service component through an item called "Headers" ( 
) which contains two child items: "Name" and "Value". This structure acts as sequence, and enables you to map data from any number of headers returned by the Web service. To map the data from the response headers to any other format supported by MapForce, connect the "Headers" structure node to a target sequence in the mapping. For example, if you connect the Headers sequence (and its children) to a Rows sequence (and its children) of a CSV component, one header would correspond to one row in the CSV file.
The Body 
represents the entity body of the HTTP message. Data at this level is binary encoded, so interacting with it directly requires MapForce mime functions. Note that you don't typically need to interact with the Body at all if the Web service expects or returns structured data such as XML or JSON. Mapping data directly to or from the Body is only necessary when calling Web services that expect or return unstructured content.
By default, the Body item is configured to parse the result if the HTTP status code ranges from 200 through 299. This means that the mapping will return an error for status codes greater than 299. Also, an error will be returned if the response cannot be parsed or the Web service cannot be called due to connection failure or DNS resolution problems. |
In some cases, you might want the mapping not to throw an error even if the HTTP status code is greater than 299. To do this, click the button next to the response Body and change the HTTP status code range. Alternatively, you can create multiple response Body items. Creating multiple Body items is useful when you want to handle the mapping conditionally depending on the HTTP status code returned by the Web service. To do this, right-click the Body of the response part, and select Add Body Node Before/After from the context menu. For example, you could create two Body items:
1.A Body for all status codes that are in the success range (200 to 299). You can configure the status codes range by clicking the button. For this scenario, you will typically want to map the Body structure to some "success" output, like a JSON or XML file.
2.A Body for all other status codes, in the range between 300 and 599. Some Web services may provide additional details about error status codes in the body. To find out the reason of the error, you can therefore map the "erroneous" Body to an output other than the "success" one (for example, a string).
When multiple Body items exist, MapForce evaluates them from top to bottom. To change the priority, right-click the Body item, and select Move Up or Move Down from the context menu. For more information about handling the HTTP response conditionally, see Handling the HTTP Response Conditionally.
Mappings containing generic HTTP Web service calls can be executed like most other mappings, namely:
•Manually, with MapForce, by clicking the Output pane. In this case, the result of the mapping call is immediately available in the Output pane. If the mapping has multiple output components like in the example above, press the Preview 
button on the desired component before running the mapping.
•Through command line or API calls, with MapForce Server (https://www.altova.com/mapforce-server). This requires compiling the mapping to a mapping execution file first (see Compiling Mappings to MapForce Server Execution Files).
•As a recurring job, with MapForce Server running under FlowForce Server control (https://www.altova.com/flowforceserver). See also Deploying Mappings to FlowForce Server.
For step-by-step examples of how to create a generic Web service call, see: