New functionalities in the "Invoke REST Web Service" action

Applies to version: 2021.1.x and above; author: Agnieszka Burda

Introduction

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:

• the value sent for the “Request body” tab;
• the value received for the “Response” tab.

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:

• int
• decimal
• boolean
• date
• datetime

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 “Invoice number” form field
• the “Date” form field
• the “Net value” form field
• the “Costs” collection consisting of:

• the “Center code” column
• the embedded “Details” collection consisting of:

• the “Cost type” column
• the “Value” column

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.

Selection window

After its acceptance, all available methods are loaded. To select, click the required method from the drop-down list.

Available methods