Applies to version: 2021.1.x and above; author: Agnieszka Burda
With WEBCON BPS you can use API interface. The article available here: https://community.webcon.com/posts/post/the-invoke-rest-web-service-action/170/ describes the “Invoke REST Web Service” action provided in Designer Studio that allows users to use external services sharing their own API. This article describes new features introduced in the aforementioned action in WEBCON BPS 2021.
JSON - grid
A simple workflow is created for demonstration purposes to obtain average exchange rates from the National Bank of Poland.
A form containing exchange rates
The “Download exchange rate” button triggering the “Invoke REST Web Service” action is added to the upper bar.
First change involves adding the option “JSON - grid” to the “Body type” field (the “Invoke REST Web Service” action → the vertical ellipsis button → “Configuration” → the “Request body” tab → “Body type”) for the “POST” http method. Once you get to the action configuration window, click the “Request data” tab and select the “POST” option in the “Http method” field.
Configuration of the “Request data” tab
The “JSON - grid” option can now be selected from the drop-down menu in the “Request body” tab. This option allows users to map values to be sent. Enter the name of the mapped value in the “Name” column and specify the form field containing the value in the “Source field” column.
Configuration of the “Request body” tab
Business rules in JSON - grid
Another change consists in adding the “Business rule” column for the JSON - grid request in the “Request body” and “Response” tabs. This change allows users to modify sent and received data. If the icon in the “Business rule” column is greyed out, it is then not used.
Configuration of the “Response” tab
Clicking the greyed out icon opens the rule configuration window where the “Input value” is inserted by default. The “Input value” refers to:
By using this parameter you can edit data before they are sent or received. For example, when a system receives a value that prior to its saving requires multiplying by 0.01, you need to create a rule that executes such calculation. What is more, you can define the format of the returned value, which is discussed in the following chapter.
Business rule edition
Once the calculations are executed, the value is assigned to the indicated form field. For the values which are sent the situation is similar – the mapped form field is converted in accordance with the created business rule and then sent.
Changing the data type
WEBCON BPS 2021 now allows users to change the type of the mapped value. So far, the conversion of the value type to the form field type indicated in the “Response” tab was of string type and occurred in the culture of a particular server. The 2021 version preserves the mechanism that converts all data to string values in the culture of a current server. Additionally, a user can define the data format by selecting one of the below values from the drop-down list:
Changing the value type in the “Response” tab
For example, when a floating-point number (decimal) is to be inserted in the decimal-type form field, you can select the correct type in the value mapping configuration. As a result, you prevent unnecessary conversion of data.
Data types also appeared in the business rule configuration.
Changing data types in the business rule
Additionally, when configuring the rule, you can change the type of parameter that is used in it. You can enter the configuration window by right-clicking the parameter and selecting the “EDIT” option from the drop-down menu.
Changing the type of the “Input value” parameter
The available parameter types are the same as the ones available in the business rule configuration.
JSON - grid to JSON conversion
When a request is created in the “JSON - grid” format, it is possible to convert it to “JSON” format without losing data structure.
Request body in the “JSON - grid” format
To do that, change the data type in the “Body type” field from “JSON - grid” to “JSON”. A message appears requesting confirmation for value mapping.
A message requesting user to confirm JSON format generation
Once you confirm the conversion, the data are displayed in the correct format.
Request body in the “JSON” format
Receiving embedded collection
WEBCON BPS 2021 allows users to embed collections.
In the below-described example an API interface provided by the National Bank of Poland (NBP) is used. Table A available at http://api.nbp.pl/api/exchangerates/tables/A contains current average currency exchange rates. As demonstrated in the screenshot below, apart from the “Table”, “No”, and “EffectiveDate”, the “ExchangeRatesTable” also contains the “Rates” collection that includes exchange rates for individual currencies.
Table A of the National Bank of Poland API interface
If you want the data to be returned with the preserved structure in the form, start with configuring connection with NBP and then define correct table and method.
The “Request data” tab
The data structure can be easily loaded using the “Load” button available in the “Response” tab.
Loading the structure
Note the two-level structure of the data after loading them correctly.
The mapped data structure
To map data correctly, at the slash (“/”) level select the item list to which values are to be loaded. This list is also automatically linked at the “Rates” level with no edition option. Note that it is not possible to link different lists to embedded collections.
Mapping item list
It is now necessary to define correct columns from the selected “Average exchange rate” item list for the mapped values.
Mapping item list columns
As presented in the attached screenshot, the average currency exchange rates are mapped onto the “Average exchange rate” item list as intended after hitting the button.
The exchange rates mapped onto the item list
If, apart from mapping values onto the item list, it is necessary to map values onto different form fields, add two technical columns: “_Date” (date and time) and “_Number” (single line of text). Those were also added in value mapping settings in the action configuration.
Mapping values onto item list technical columns
The method described allows system to save date and number in technical columns. To transfer values from those columns to form fields use the “Change value of single field” action. Two new actions (named “Change date” and “Change number”) changing value of a field are added to the “Download exchange rate” button that triggers the “Invoke REST Web Service” action.
Two new actions changing form field value
The “Change date” action downloads values from the “_date” item list column and selects unique values using the “Distinct” function. As all columns contain the same value, this function returns only one date. Note here that instead of the “Distinct” function it is also possible to use the “Min” or “Max” function.
Configuration of “Change value of single field” action
The “Change number” action is configured analogously.
Note that after hitting the button in the form the values are correctly mapped onto the “Date” and “Number” form fields.
The values mapped onto the “Number” and “Date” form fields
Sending embedded collection
To demonstrate the sending embedded collection functionality, a simple cost invoice workflow is created that contains an analytically distributed item list.
Cost invoice form
As demonstrated in the attached screenshot, there are two values in the “Center code” column against which the values in the “Cost type” column are narrowed down.
The structure of the data to be sent is saved in JSON format and presented in the below screenshot.
The structure of the values sent
The data sent are:
The “Send invoice” button triggering the “Invoke REST Web Service” action is created for sending the data.
After adding the connection to the web service to which the data are sent and selecting the “POST” method, the structure of the mapped values is created in the “Request body” tab.
Configuration of the “Request body” tab
Downloading data from Swagger
The last of the new functionalities introduced in the BPS 2021 version is the ability to connect using Swagger. In the action configuration window, the “Request data” tab provides now the “Based on swagger” section.
Downloading data from Swagger
After hitting the “Load” button, a “Swagger data” window appears where you need to provide link to Swagger.
After its acceptance, all available methods are loaded. To select, click the required method from the drop-down list.