Examples of using REST API

Applies to version: 2020.1.x; author: Marcin Wołosz

• Introduction
• Authentication
• Use of REST API
• Summary

Introduction

The WEBCON 2019 version introduced the possibility of using REST API technology to create programming integration solutions with the system. The REST API provides full support and allows you to start new workflow instances, transition paths, and modify the content of the instances. WEBCON BPS 2020 has API in version 2.0 which will be used in the examples below.

Authentication

API uses bearer token authentication. How can you get a token? You need to register the application in the admin panel (available only for the administrator of the default content database . The panel is available at: [Portal_address]/adminPanel.

Registering the application will generate two important pieces of information: ClientID and ClientSecret, which are necessary to get this token. Since the launch of the 2020 version, it is a possibility to create multiple ClientSecret.

The very important thing is saving the generated key, because it isn’t stored by us and if you will lose it, it cannot be viewed again.

There is also a possibility of using “Impersonation” which allows you to call API in the context of a specific user.

Before starting your tests, you need to give your newly registered App the privileges to start the process – you can do this in exactly the same as you would assign privileges to regular users or groups.

Use of REST API

For testing we will use the API verification tool – called Postman and simple, two-step process containing several standard form fields and one item list.

• Obtaining a token – /api/login

In the Postman we create the first REQUEST – POST for the LOGIN method. No authentication is required.

In the header we set ‘Content-Type’ to application/json and in the body using JSON we send the previously generated ClientID and ClientSecret.

REQUEST:

URL: https://at03.webcon.pl/api/login

This method has returned a token needed for authentication in subsequent methods.

RESPONSE:

Postman:

• Loading instance info - /api/data/v2.0/db/{dbId}/elements/{id}

The instance information is downloaded using GET REQUEST and {dbID}, {id} parameters.

In this method we must use the token for authentication:

In response we receive information about the instance.

• Starting a new instance – /api/data/v2.0/db/{dbId}/elements

In this case we will use the same authentication as in the previous example. The only change is to use POST REQUEST and add required PATH parameter containing the path we want to transition with.

In the body it is necessary to send information such as: workflow ID/GUID, business entity ID/GUID and form type ID/GUID. Sending all form fields is not necessary. The GUIDs of form fields can be used from the previous example.

Example of REQUEST.

URL: https://at03.webcon.pl/api/data/v2.0/db/6/elements?path=15

RESPONSE

The workflow instance registered by using REST API:

• Updating an existing instance – /api/data/v2.0/db/{dbId}/elements/{id}

The modification requires PATCH REQUEST. In the simplest case, it involves saving the workflow  instance – you can optionally use a transition path through the REST API. In the body we send only what we want to modify. Other values don’t have to be sent.

REQUEST:

URL: https://at03.webcon.pl/api/data/v2.0/db/6/elements/21

REPONSE:

Summary

The above examples are only the small part of what we can do with REST API. We can also use it to:

• Download and modify attachments
• Delete instances
• Download tasks for users
• Download information about processes
• and a lot more 

The full documentation in the swagger form is available at: [Portal_address]/api and in the version with SharePoint at: [Portal_address]/webconbps