Try Using Questetra Rest API with Swagger

Hi there!

In this guide I would like to explain how to use Swagger, which is an environment with various processes and mechanisms which can be used to execute operations and test the functionality of your Workflow platform.

There are two types of Web API in Questetra BPM Suite: the System Settings API, in which you can configure User registration information and system privileges, and the Workflow API, in which you can operate Processes and Tasks. To begin with I will focus on the Workflow API.

To access the API click on [API Reference] in the Useful Links section of the left-side menu on any of Questetra’s main screens. In the page that opens click the [API Reference] button under “Workflow API”, and a Swagger page will open where all the available functions are listed.

The functions are grouped according to the areas they relate to, and are categorised as:

GET: which retrieves information from the database
POST: which makes updates to the database *

Please note: POST methods are only available in Professional Edition, with the exception of
- /API/Admin/ItemCache/delete
- /API/OR/ProcessInstance/{processInstanceId}/Star/add
- /API/OR/ProcessInstance/{processInstanceId}/Star/remove

To use a function simply click on it to expand the section revealing the parameters which must be input to get a response and beneath that, the responses.

Authorize with Basic Authentication

In order to use the functions you must first have authorization and login by clicking the lock symbol to the right of the function header.

It is possible to authorize using one of the following methods:

Basic Authentication
OAuth2

Basic Authentication is easier so I will use this method in this example. The explanation for how to set up OAuth2 is at the end of the article.

When you click on the lock symbol it will open a window where you can input your email address and password to access the APIs with Basic Authentication.

First you must enable API access in Questetra by going to System Settings > API Clients > API access with Basic Authentication, check the box labelled “Enable API access with Basic Authentication” and click Save.

The password you must use can be found in Account Settings > Password > API Password.

Once access has been granted, click on the “Try it out” button to enable use of the function, revealing a blue button labelled “Execute”. You must input into the required parameters and then click the Execute button.

Once the operation has been executed the responses will be displayed in the Responses section.

If the execution fails due to a problem, the error details will also be displayed indicating the cause. A list of all possible errors can be found on this reference page.

Using GET API to Retrieve a Record

You can use the GET method to retrieve data from your Workflow database.

For example, the function /API/Admin/ProcessAuthority/list is used to get data about Users who have privileges for a particular (Workflow) App.

To retrieve this information you must input the Id of the Workflow App (which can be found in the Detail page of the Process) in the processModelInfoId field, and select the type of privilege. In the example below I have selected 0 indicating App Administrator Authorization.

When this function is executed it will generate a response body in the JSON format containing the requested information, as well as a URL which can be used to access the same data.

For example, in the following article explains how to retrieve Task list data in the Workflow using the Request URL.

Downloading Process and Task Lists Using Workflow API (reportId)

If you want to check a different type of Process authorization or a different App you can re-enter the parameters and execute the function again.

Using POST API to Update a Record

Now I will use the POST method to update information in the workflow infrastructure.

Note that the content executed by POST will actually rewrite the database, so please be careful.

To demonstrate how the API can be used to update your workflow platform, I will show you the function /API/Admin/ProcessAuthority/addToQuser, which is used to grant Process authorization to users.

For this you must input the Id of the Workflow App for which you want authorization to be granted (which can be found in the App Detail page), and the Id of the User (which can be found at System Settings > User List > User Detail page). You must also select a number from the “type” dropdown indicating the level of authorization you wish to grant. In this example we will select type 2, indicating Data Viewer Authorization.

Click Execute to apply the change, and you can check whether the privilege has been successfully applied by going to System Settings > App Authorization and clicking on the App you specified. You should see that the specified User has been added to the authorization under the appropriate section determined by the type of authorization you selected.

The data that can be viewed/updated is based on the permissions granted to the user authenticated by Swagger
- (Content that can be viewed and manipulated in the Workflow)
System administration privileges are required to operate APIs in the /API/Admin/… category.

Appendix

Login with OAuth2

To login using OAuth2, first you must register Swagger as an OAuth2 client profile in Questetra, then allow access to the Workflow platform in the Swagger authorization screen. Go to System Settings > API Clients > OAuth2 Clients. Click [Add OAuth2 Client] and enter the client name and a redirect URL. The redirect URL will usually be in the following format:

https://<your questetra domain>/s/swagger/oauth2-redirect.html

Click Add, and your Client ID and Client Secret will appear

Once this is set up you will be provided with a Client ID and a Consumer Secret. Input both of these into the respective fields in the authorization login window and select either of the scope checkboxes.

Please note that Consumer Secret in the API Clients window and client_secret in the authorization window are the same thing.

If there is a problem with the redirect URL and error page will be displayed showing the appropriate URL, so you can copy this into your API Client settings to fix the error.

Once the settings are configured correctly, click Authorize and a confirmation window will open. Check the authorization is being given to the correct account and click Authorize again to confirm it.