The “Invoke REST Web service” action

Applies to version: 2020.1.x; author: Dawid Golonka

Introduction

One of the functionalities in WEBCON BPS system is the ability of using the REST API interface. API is the basic method of data exchange between two systems and it is often used both to download data and transfer it from WEBCON BPS to other applications (e.g. data transfer to the vacation system). For more information about examples of using API see Examples of using REST API.

This article describes the “Invoke REST Web service” action that allows you to use external services that provide their API.   

Configuration

The simple workflow has been created that will return additional information about a business entity (such as KRS number or address) based on the NIP number.

Fig. 1. The workflow

The workflow consists of three steps:

• Input data – a user enters the NIP number of the business entity whose data they want to obtain.
• Check – a user checks the entered data. If data are correct – the instance goes to the “Download data” path on which the “Invoke REST Web service” action is executed. If not -  the instance can be moved to the first step.
• Information checked – the instance goes to the last step where information about business entity will be stored with the date it was retrieved.

The screenshot below presents the form at the first step – enter the NIP number:

Fig. 2. The registration step

Next, the instance goes to the step where the information about the business entity is downloaded from the external API. To do this – click the “Download data” button.

Fig. 3. The “Download data” button on the form

After clicking this button, the “Invoke REST Web service” action will be executed.

Configration of the action

Fig. 4. The “Invoke REST Web Service” action

On the “Authentication” tab, there are two options:

• Based on data connection – based on the previously created connection
• Custom – based on the custom configuration

Fig. 5. The configuration of the action – Authentication tab

When selecting the type of authentication, the number of required fields to be completed changes.

At the bottom of the panel, enter the base service instance URL; it is also possible to disable the HTTPS certificates checking.

On the “Request data” tab enter the URL/REST request suffix. In this example – the suffix with NIP (provided from the form) and today’s date (system variable) are given.

To load responses for later mapping, instead of form fields, you must manually enter sample data (NIP number and date), because before creating the first workflow instance – these fields do not return any values.

There are five HTTP methods:

• GET
• POST
• PUT
• PATCH
• DELETE

The POST, PUT, and PATCH methods additionally require completing the content of the request on the next tab. In the “Custom headers” tab, you can add additional request headers such as host or API key data.

Fig. 6. The Request data tab

In the “Response” tab, you can define the mapping of the form field to the form where the data received from the response (on the defined HTTP request) will be overwritten.

Fig. 7. Form fields mapping

The form will include the data such as:

• Company name
• NIP
• REGON
• KRS
• Address

Fig. 8. The Download data” path

The “Check date” contains information on which day the data was downloaded. Now you can move the instance to the final step where data will be stored in read-only mode To quickly gain access to data in the future, NIP has been included as part of the instance number.

Error handling

This action allows you to configure the incorrect responses handling. There are two variants of handling http codes:

• Abort execution if http code belongs to any of the 300, 400 or 500 group
• Continue execution if http code belongs to any of the 300, 400 or 500 group

In the form below, the NIP number, which does not belong to any business entity was entered. As you see, the error was returned that stop execution of the action. Error code means that the incorrect parameter has been introduced in the form.

Fig. 9. The error displayed on the form

The second variant makes it possible to continue the execution of the request despite the error code. This option is especially useful when the API you use has a built-in exception handling. The API used in this article may return a value  with an error message when an error occurs – to check this functionality, map this message to the “Error description” form field. It will be displayed only when the “Invoke REST Web service” action returns the error. In this case, the remaining fields on the form will be hidden.

Fig. 10. The error displayed on the form

After downloading data for the given NIP, you did not receive any error message from WEBCON BPS. The detailed information about the error, you can find in the form field where the message returned by API has been provided – it informs about incorrect NIP number.

The action of invoking the Web service also allows you to map the Code and Body values of the response, both in the case of positive and incorrect invoke. In more complex cases, this can enable error handling on the WEBCON BPS side.

Below there is the request with the error:

Fig. 11. Code and Body responses for the incorrect request