Starting workflows from an external system – REST API

Applies to version: 2020.1.x and above; author: Tomasz Słuszniak

One of the methods to start a bpm workflow in WEBCON BPS is to use REST API BPS. It can be especially useful in situations such as:

• Data exchange between different WEBCON BPS instances – e.g., there is an internal application for your organization and a public application available for your clients.
• Data exchange with external systems e.g., CRM, ERP.

Example of use

Let us show you how the REST API can be used to start a workflow in the design process.

The first step will be to create an application that allows access to the API – in WEBCON BPS Portal, enter the “Administration” tab and then, from the “Integration” tab, select the API option and create a new application by using the “New API application” button.

A window will appear on the screen in which you must fill in information about the application. When starting the workflow through REST API, a user whose data is filled in the Name, Login, and E-mail fields will be visible as the author. The login must be entered in the UPN format and cannot be repeated (in AD there cannot be the user with the same login).

Impersonation – the option allows the REST API to perform the operations on behalf of another user. You can also specify in which application the impersonation will be possible.

After saving the application, the next step will be to create the private key used when calling the REST API – click the “Generate new client secret” option.

The key generated in this way should be saved because it will not be shown again.

To perform the operations through REST API, log in to the system. In this case, use the data when creating the API application) – you need to ClientID and ClientSecret (private key). When starting the workflow, the impersonation option will also be used to prevent the operations for which the user has no privileges (e.g., inability to start or edit the workflow).

To log in, send a request using the POST method to the following address:

http://adres_portalu_webcon_bps/api/login

In response, you will receive a token that allows you to perform the subsequent operations through REST API.

The token must be provided as a header in the subsequent requests.

To start the workflow, send the POST request to the following address:

http://portal_address/api/data/v2.0/db/1/elements?path=

GUID of the path can be obtained from WEBCON BPS Designer Studio by clicking the button next to the path’s ID.

An example of a request address:

http://wdr04/api/data/v2.0/db/1/elements?path=89083a10-b8f4-44f8-b500-df2cb417aa98

In the request BODY, provide the parameters to initialize the workflow instance:

All GUIDs can be found in WEBCON BPS Designer Studio.

In response to this request, you will receive an ID, Instance number, and Status.

The workflow was correctly started, you can verify the result on the form in Portal:

Call API also started the “Run subworkflow (SQL)” action which has been configured in the first example of starting workflow methods.

A detailed description of REST API and WEBCON BPS SDK can be found at https://developer.webcon.com/resources/.