The Call web service process element is a means of sending web service method requests and processing the response as part of a business process flow. Before using this element, you need to set up web service integration in the Web services section of the system designer.
The function of the Call web service element largely depends on the integrated web service. For example, you can use this element to obtain latest exchange rates as part of a process flow (Fig. 1), by calling a web service, which returns currency exchange rates in its response.
When its incoming flows are activated, the Call web service element:
- Executes the needed web service method request with the specified request parameters.
- Waits for a response from the web service, according to integration settings.
- Records results to its outgoing parameters.
- Activates own outgoing flows.
To integrate a web service into your business process, add the Call web service element to the Process Designer working area, select a web service and method to call, then specify the parameter values on the Call web service element setup area (Fig. 2).
Which service to call? – select one of previously set up web service integrations For example, if you previously set up integration with the “Fixer” currency exchange rate service, you will be able to select it here. Click the button to open a new web service integration page. You can set up integration with a new web service on this page. If a web service is already selected, click to open its setup area.
Which method to call? – select a web service method to call when executing the web service request. The available values of this parameter depend on web service integration specifics.
Maximum execution time, in seconds – Limit total time for calling the web service by this element. The limit includes retries. When the execution time is exceeded and there have been responses with error status (400, etc.), the outgoing parameters will be populated according to the last received response from the web service.
Request parameters – If the selected method has request parameters, they will become available here, once a method is selected. Business processes treat them as “incoming” parameters for the corresponding Call web service process element.
For example, according to the web service information available at http://fixer.io/, we have set up integration with this web service using the following request parameters:
Base currency – the base currency for exchange rates to retrieve.
API key – the web service API key. You will need to register on https://fixer.io/. to obtain your API key.
Endpoint – the web service endpoint (will be added right after URI and before the query parameters). In the case of http://fixer.io/ it can be either “latest” – to request latest available exchange rates, or a specific date in the text format (such as “2000-01-03”) – to request rates for that date. All required parameters should be populated. If left empty, the query parameters will still be part of request, but will not have values. For example: “?parameter-With-Value-1=Value-1¶meter-With-No-Value-1¶meter-With-No-Value-2”.
If the request parameter is a collection (the “Is array” checkbox is selected in the properties of the parameter at the web service record), the nested collection parameters will be displayed under the collection name in the process element parameters (Fig. 3). For example, Creatio “batch query” service can insert several records (e.g. contacts) to Creatio. To do this, the service would require information to write into the fields of each inserted record (e.g. contact names and types). In this case, you can pass the values as a request parameter of an array type, where “Name” and “Type” will be nested parameters and each instance of the collection would represent data for a separate contact record.
The values of collection parameters of one Call web service process element can be mapped to the nested parameters of another collection of a Read data or Call web service process element(Fig. 4, Fig. 5).
The parameters of the collection of process elements can be mapped to the process parameter of the “Collection of values” data type (Fig. 6).
When the Call web service element is activated, it executes a web service request, obtains and parses the response, and populates its outgoing parameters. Each Call web service element has the two outgoing parameters for processing errors – Success, Http status code:
If the call is successful (response code is <400) the Success parameter will be set to “true”.
If the call resulted in an error (response code is 400 and up), the Success outgoing parameter will be set to “false” and the Http status code parameter will be populated. Use these parameters to process errors of the web service call in the business process. You can call the web service later automatically, use other call parameters or terminate the process.
Each response parameter that you set up for a web service method will be added as an additional outgoing parameter to the Call web service element, where this method is selected in the Which method to call property.
To use this information in your business processes, map process, and process element parameters to the outgoing parameters of the Call web service element.
In the current “Fixer” web service integration, the following outgoing parameters will be available in addition to the error processing parameters: “Base currency” (“string” parameter), “Date” (“date” parameter), and a separate decimal parameter for each currency rate, i.e., “RatesAUD”, “RatesEUR”, etc. You can display the received data via the pre-configured page by setting up its field connection with the corresponding outgoing parameters of the Call web service element (Fig. 7, Fig. 8). As a result, the page fields will contain the data received from the web service response.
Response parameters of a web service can also be collections. The Response parameters are available on the Parameters tab of the Call web service element in the advanced mode (Fig. 9). The nested collection parameters will be displayed under the collection name.
The values of collection parameters of a Call web service process element can be mapped to the nested parameters of another collection of a Read data or Call web service process element (Fig. 4, Fig. 5).Additionally, each item of the collection can be mapped to an individual subprocess instance in the Subprocess element, Read more about using data collections in the “Process collections” article.
The Call web service may produce a tree-like data collection. The Subprocess element can only parse flat structures fully. When dealing with a multi-level data collection, the Subprocess element will only extract and make available for mapping top-level parameters and none of the deeply nested structures.