There are two Web APIs of Questetra BPM Suite: the System Settings API, in which you can configure User registration information and system privileges, and Workflow API, in which you can operate Processes and Tasks. In this case, I will show you how to download a list of Processes (instances) and Tasks via the Workflow API using curl command in bash. By using the Workflow API, you can create scripts that automatically download data of Processes/Tasks on a regular basis.

On Mac and Linux, you do not need to install the curl command. For Windows, it can be used on Windows Subsystem for Linux, etc.
It is based on the premise that the following tasks are to be performed with an account that has “Data Viewer authority” for the target Workflow App. You can check whether your account has the Data Viewer privileges at [Account Settings] > [Authorization].

To Download Data of Processes

Questetra BPM Suite has a process search function in its Web UI. Like the figure below, you can search, for example, specifying the Title of Processes.

Result of Process search with Title “test”

This search result can be obtained via the Workflow API. When downloaded, for example, in CSV (UTF-16, Excel compatible) format, the following search results are returned from API

""App ID"	"App Name"	"Category"	"Version"	"Process ID"	"Status"	"Start User ID"	"Start User"	"Start Organization ID"	"Start Organization"	"Title"	"Start Time"	"End Time"
97	"Travel Request-Tutorial"	""	1	212	"Running"					"test"	"2019-01-16 14:32:58"	
96	"Message Start Event (HTTP)-Turorial-curl	""	4	208	"Running"					"TEST"	"2019-01-04 13:32:50"	
91	"Message Start Event (HTTP)-Turorial"	""	1	202	"Running"					"test"	"018-12-12 17:21:27"
...

There are three types of API endpoints that you can download Processes from.

  • /API/OR/ProcessInstance/listCsvUtf16: CSV (UTF-16) format
  • /API/OR/ProcessInstance/listCsv: CSV (UTF-8) format
  • /API/OR/ProcessInstance/list: JSON (UTF-8) format

Among them, /API/OR/ProcessInstance/listCsvUtf16 for the “CSV download (Excel compatible)”, and /API/OR/ProcessInstance/listCsv for the “CSV download (UTF-8)” corresponds respectively to options on the Process search page Download drop-down menu.

In Web UI, there is a download menu at the top of the search results

Preparation of search parameters

The following three parameters are required for any of the API endpoints:

  • start: specifies starting position on the search result list
  • limit: specifies the maximum number of results to obtain
  • criteria: specifies the search conditions

For start (0 in default) and limit (1 in default, max. 1000), you just specify an appropriate number according to your purpose. Regarding criteria, you need some preparation.

criteria is XML data that specifies the search condition. With search conditions, for example;

  • Processes of “Simple Request App (App ID 6)”
  • Process End Date is in between 1st and 30th of September, 2018
  • Processes that have ended
  • Indicate Data Item of “Numeric 0 (Data number 0)” and “Date 0(Data number 1)” on the search results

the XML will be the following.

<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>6</process-model-info-id>
<end-date-from>2018-09-01</end-date-from>
<end-date-to>2018-09-30</end-date-to>
<states>
<state>ENDED</state>
</states>
<data>
<decimal>
<data-definition-number>0</data-definition-number>
<value></value>
<view></view>
</decimal>
<date>
<data-definition-number>1</data-definition-number>
<value></value>
<view></view>
</date>
</data>
</process-instance-criteria>

criteria is used also for Process searches on the Web UI. Since it is difficult to understand the description format of criteria and write the XML on your own, we will use the Google Chrome “Inspect” tool to retrieve the criteria used in Web UI and use it for API access in this article. First I will show you how to get criteria.

First, log into Questetra BPM Suite with Google Chrome, then open the “Workflow” panel. Click on [All Processes] in “Process Task Status Check on the left menu to jump to the Process search page.

If the account you are using does not have permission to view data in any Workflow App, the menu of “All Processes” will not be displayed.

On this page, open the “Inspect” tool on the right-click menu. The Inspection tool will appear, splitting the window. When you perform Process search while the Network tab on the Inspect tool is selected, you can check the request sent to Questetra BPM Suite from your browser. Set the filter/display items according to the data you want to acquire with the API, and click on the [Update] button.

The item displayed with the name “list?_dc={NUMBER}” is the request that has been sent.

Procedure to confirm the request sent to Questetra BPM Suite

Click on the item name to open its detail. criteria is written in Form Data at the bottom. Save this data as an XML file.

Now, let’s access the Workflow API with the curl command.

Obtaining Process search results with curl command

Let’s get a search result by accessing /API/OR/ProcessInstance/listCsvUtf16 which returns Processes that satisfy the search conditions in the format of CSV UTF-16. The format of CSV data in UTF-16 is friendly for importing to Excel.

In Questetra BPM Suite, OAuth 2 and Basic Authentication are available for accessing APIs. We will use Basic Authentication as is easier to set up.

Concerning Basic Authentication in Questetra BPM Suite, please refer to the article “Synchronizing User Information with Local Data (Preparatory Chapter)”, in which procedures from enablement setting to confirmation of the password are explained.
$ curl -u {EMAIL ADDRESS}:{PASSWORD for Basic authentication} \
> 'https://example.questetra.net/API/OR/ProcessInstance/listCsvUtf16' \
> --data-urlencode criteria@process_criteria.txt \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0'

In order to pass the URL encoding to the curl command, send each parameter as key@path or ‘key=value’ by the –data-urlencode option. For short parameters, it is better to embed them directly in the command as ‘key=value’. Since the criteria, which is XML data, is too long to embed directly, in the above command example it passes what has been saved in a text file. By writing criteria@process_criteria.txt, the content of process_criteria.txt is passed to the parameter, criteria.

The parameter limit is for specifying the upper limit of the number of the search results (1 in default, max. 1000), and start specifies from which search result number to start returning (0 in default). If you want to obtain more than 1000 results, you need to change the value of start and repeat accessing the API.

Also, it is possible to perform Basic Authentication with -u option in curl command. Write the email address and password in separated by a colon (:).

Since CSV data is encoded in UTF-16LE, it will often be garbled when it is output to bash as stdout. To output the results to a file, set as the following:

$ curl -u {EMAIL ADDRESS}:{PASSWORD for Basic authentication} \
>...(omitted)... > output.csv

The following is an example of the returned result

"AppID"	"App Name"	"Category"	"Version"	"Process ID"	"Status"	"Start UserID"	"Start User"	"Start Organization ID"	"Start Organization"	"Title"	"Start Time"	"End Time"	"Numeric 0"	"Date 0"
6	"Simple Request App"	""	2	15	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test"	"2018-09-10 16:07:28"	"2018-09-10 17:37:41"	"1,000"	"2018-09-10"
6	"Simple Request App"	""	1	14	"Completed"	1	"Tutorial"	1	"00 Questetra"	"TEST"	"2018-09-10 15:40:05"	"2018-09-10 17:34:00"	"1,000"	"2018-09-10"

You can use it likewise for /API/OR/ProcessInstance/listCsv which returns results in UTF-8 CSV format and /API/OR/ProcessInstance/list in UTF-8 JSON format. Below are examples of the search results of those respectively.

/API/OR/ProcessInstance/listCsv (CSV, UTF-8)

"AppID","App Name","Category","Version","Process ID","Status","Start UserID","Start User","Start Organization ID","Start Organization","Title","Start Time","End Time","Numeric 0","Date 1"
6,"Simple Request App","",2,15,"Completed",1,"Tutorial",1,"00 Questetra","Test","2018-09-10 16:07:28","2018-09-10 17:37:41","1,000","2018-09-10"
6,"Simple Request App","",1,14,"Completed",1,"Tutorial",1,"00 Questetra","TEST","2018-09-10 15:40:05","2018-09-10 17:34:00","1,000","2018-09-10"

/API/OR/ProcessInstance/list (JSON, UTF-8)

{
  "count": 2,
  "processInstances": [
    {
      "activeTokenNodeName": null,
      "data": {
        "0": {
          "dataType": "DECIMAL",
          "id": 2424,
          "processDataDefinitionNumber": 0,
          "subType": null,
          "value": "1,000",
          "viewOrder": 1
        },
        "1": {
          "dataType": "DATE",
          "id": 2425,
          "processDataDefinitionNumber": 1,
          "subType": "DATE_YMD",
          "value": "2018-09-10",
          "viewOrder": 2
        }
      },
      "processInstanceDebug": false,
      "processInstanceEndDatetime": "2018-09-10T17:37:41",
      "processInstanceId": 15,
      "processInstanceIdForView": "p15",
      "processInstanceInitQgroupId": 1,
      "processInstanceInitQgroupName": "00 Questetra",
      "processInstanceInitQuserId": 1,
      "processInstanceInitQuserName": "Tutorial",
      "processInstanceSequenceNumber": 2,
      "processInstanceStartDatetime": "2018-09-10T16:07:28+0900",
      "processInstanceState": "ENDED",
      "processInstanceTitle": "Test",
      "processModelInfoCategory": "",
      "processModelInfoId": 6,
      "processModelInfoName": "Simple Request App",
      "processModelVersion": 2
    },
    {
      "activeTokenNodeName": null,
      "data": {
        "0": {
          "dataType": "DECIMAL",
          "id": 2366,
          "processDataDefinitionNumber": 0,
          "subType": null,
          "value": "1,000",
          "viewOrder": 1
        },
        "1": {
          "dataType": "DATE",
          "id": 2367,
          "processDataDefinitionNumber": 1,
          "subType": "DATE_YMD",
          "value": "2018-09-10",
          "viewOrder": 2
        }
      },
      "processInstanceDebug": false,
      "processInstanceEndDatetime": "2018-09-10T17:34:00",
      "processInstanceId": 14,
      "processInstanceIdForView": "p14",
      "processInstanceInitQgroupId": 1,
      "processInstanceInitQgroupName": "00 Questetra",
      "processInstanceInitQuserId": 1,
      "processInstanceInitQuserName": "Tutorial",
      "processInstanceSequenceNumber": 1,
      "processInstanceStartDatetime": "2018-09-10T15:40:05+0900",
      "processInstanceState": "ENDED",
      "processInstanceTitle": "TEST",
      "processModelInfoCategory": "",
      "processModelInfoId": 6,
      "processModelInfoName": "Simple Request App",
      "processModelVersion": 1
    }
  ]
}

To Download Data of Tasks

As with Processes, you can retrieve information of Tasks via Workflow APIs. criteria is required as with Process search, and you can use it in the same way by switching the “Display at the level of processes” at the top right of the page to “Display at the level of task operations”.

There are also three types of API endpoints for downloading Tasks provided.

  • /API/OR/Workitem/listCsvUtf16: CSV (UTF-16, Excel compatible) format
  • /API/OR/Workitem/listCsv: CSV (UTF-8) format
  • /API/OR/Workitem/list: JSON (UTF-8) format

Obtaining Task search results with curl command

Let’s access /API/OR/Workitem/listCsvUtf16 which returns Tasks that satisfy the search conditions in the format of CSV UTF-16. The following is an example of commands:

$ curl -v -u {EMAIL ADDRESS }:{PASSWORD for Basic authentication} \
> 'https://shichijo-onmae-134.questetra.net/API/OR/Workitem/listCsvUtf16' \
> --data-urlencode criteria@workitem_criteria.txt \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0' > ~/Desktop/output.txt

Even though the target of search has changed from Processes to Tasks, the parameters are the same as with Process search. Note that the Task search page is where to look for criteria. Also, since it is encoded in UTF-16LE as with the Process search, it will be garbled in many cases on stdout. It is better to output to a file and import to Excel.

Below is an example of the result. The third result and after are omitted.

"App ID"	"App Name"	"Category"	"Version"	"Process ID"	"Status"	"Start User ID"	"Start User"	"Start Organization ID"	"Start Organization"	"Title"	"Start Time"	"End Time"	"Node Number"	"Step Name"	"Status"	"Deadline"	"User ID"	"User"	"Organization ID"	"Organization"	"Offer Time"	"Allocate Time"	"Start Time"	"End Time"	"Numeric 0"	"Date 1"
6	"Simple Request Ap"	""	2	15	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test"	"2018-09-10 16:07:28"	"2018-09-10 17:37:41"	2	"Confirmation"	"Finished"		11	"Canarias"	2	"10 Management department"	"2018-09-10 16:07:44"	"2018-09-10 17:37:34"	"2018-09-10 17:37:34"	"2018-09-10 17:37:38"	"1,000"	"2018-09-10"
6	"Simple Request Ap"	""	2	15	"Completed"	1	"Tutorial"	1	"00 Questetra"	"TEST"	"2018-09-10 16:07:28"	"2018-09-10 17:37:41"	1	"Apply"	"Finished"		1	"Tutorial"	1	"00 Questetra"	"2018-09-10 16:07:28"	"2018-09-10 16:07:28"	"2018-09-10 16:07:28"	"2018-09-10 16:07:42"	"1,000"	"2018-09-10"
...

You can use it likewise for /API/OR/ProcessInstance/listCsv which returns results in UTF-8 CSV format and /API/OR/ProcessInstance/list in UTF-8 JSON format. Below are examples of the search results of those respectively.

/API/OR/Workitem/listCsv (CSV, UTF-8)

"App ID","App Name","Category","Version","Process ID","Status","Start User ID","Start User","Start Organization ID","Start Organization","Title","Start Time","End Time","Node Number","Step Name","Status","Deadline","User ID","User","Organization ID","Organization","Offer Time","Allocate Time","Start Time","End Time","Numeric 0","Date 1"
6,"Simple Request App","",2,15,"Completed",1,"Tutorial",1,"00 Questetra","Test","2018-09-10 16:07:28","2018-09-10 17:37:41",2,"Confirmation","Finished",,11,"Canarias",2,"10 Management department","2018-09-10 16:07:44","2018-09-10 17:37:34","2018-09-10 17:37:34","2018-09-10 17:37:38","1,000","2018-09-10"
6,"Simple Request App","",2,15,"Completed",1,"Tutorial",1,"00 Questetra","TEST","2018-09-10 16:07:28","2018-09-10 17:37:41",1,"Apply","Finished",,1,"Tutorial",1,"00 Questetra","2018-09-10 16:07:28","2018-09-10 16:07:28","2018-09-10 16:07:28","2018-09-10 16:07:42","1,000","2018-09-10"
...

/API/OR/Workitem/list (JSON, UTF-8)

{
  "count": 4,
  "workitems": [
    {
      "allocateDatetime": "2018-09-10T17:37:34+0900",
      "allocatedQgroupId": 2,
      "allocatedQgroupName": "10 Management department",
      "allocatedQuserId": 11,
      "allocatedQuserName": "Canarias",
      "offerDatetime": "2018-09-10T16:07:44+0900",
      "data": {
        "0": {
          "dataType": "DECIMAL",
          "id": 2424,
          "processDataDefinitionNumber": 0,
          "subType": null,
          "value": "1,000",
          "viewOrder": 1
        },
        "1": {
          "dataType": "DATE",
          "id": 2425,
          "processDataDefinitionNumber": 1,
          "subType": "DATE_YMD",
          "value": "2018-09-10",
          "viewOrder": 2
        }
      },
      "endDatetime": "2018-09-10T17:37:38+0900",
      "failType": null,
      "id": 2434,
      "nodeName": "Confirmation",
      "nodeNumber": 2,
      "processInstanceDebug": false,
      "processInstanceEndDatetime": "2018-09-10T17:37:41",
      "processInstanceId": 15,
      "processInstanceIdForView": "p15",
      "processInstanceInitQgroupId": 1,
      "processInstanceInitQgroupName": "00 Questetra",
      "processInstanceInitQuserId": 1,
      "processInstanceInitQuserName": "Tutorial",
      "processInstanceSequenceNumber": 2,
      "processInstanceStartDatetime": "2018-09-10T16:07:28+0900",
      "processInstanceState": "ENDED",
      "processInstanceTitle": "TEST",
      "processModelInfoCategory": "",
      "processModelInfoId": 6,
      "processModelInfoName": "Simple Request App",
      "processModelVersion": 2,
      "starred": false,
      "startDatetime": "2018-09-10T17:37:34+0900",
      "state": "ENDED",
      "swimlaneType": "NORMAL",
      "timeLimitDatetime": null
    },
...

In this way, you can easily search for and download information about Processes/Tasks using the Web API. Please use it when you need to import business data to other systems in cases such as, “Need a backup for audit!”, or “Want to analyze the business situation!”

Appendix: How to change the sorting criteria of search results

By default, search results are sorted according to the following criteria.

  • Process search: descending order of Process Start time
  • Task search: descending order of Task Offered time

To change these sorting criteria, you must edit the criteria. If you want to obtain Process search results sorted by, for example, “ascending order of Process end time”, edit the criteria mentioned above to the following:

<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>6</process-model-info-id>
<end-date-from>2018-09-01</end-date-from>
<end-date-to>2018-09-30</end-date-to>
<states>
<state>ENDED</state>
</states>
<data>
<decimal>
<data-definition-number>0</data-definition-number>
<value></value>
<view></view>
</decimal>
<date>
<data-definition-number>1</data-definition-number>
<value></value>
<view></view>
</date>
</data>
<sort-property>processInstanceEndDatetime</sort-property>
<sort-direction>ASC</sort-direction>
</process-instance-criteria>

Add sort-property and sort-direction elements within the process-instance-criteria element, as shown in bold two lines. The sort-property element specifies the item to be used for sorting, and the sort-direction element specifies ascending/descending order. For Task search, add the two elements in the workitem-criteria element similarly.

Values specifiable to sort-property element (Process search)

Start Date time processInstanceStartDatetime
End Date time processInstanceEndDatetime

Values specifiable to sort-property element (Task search)

Task Name nodeName
Offered Time offerDatetime
Finished Time endDatetime
Deadline timeLimitDatetime
Operator allocatedQuserId

Values specifiable to sort-direction element (Common to Process/Task search)

Ascending ASC
Descending DESC