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 article, 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.

The following tasks are to be performed with an account that has “Data Viewer Authorization” for the target Workflow App. You can check whether your account has the Data Viewer privilege at [Account Settings] > [Authorization].

To Download Data of Processes

Questetra BPM Suite has a process search function in its Web UI. For example, you can search specifying the App and selecting the Data Items to display, as shown in the image below.

↑ Result of Process search specifying “Simple Request App” and adding “Amount” and “File” to display items.

To proceed to the next tutorial “Download Process Files Using the Workflow API”, an App with File-type Data Item is required. If you do not have an app with file-type data yet, make one and start some processes with files attached.

In this article, we use the “Simple Request App” from the tutorial “Creating a Travel Request App”, after adding a File-type Data Item to it.

This search result can be obtained via the Workflow API. When downloaded, for example, in CSV (UTF-8) 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","Token Current Position","Amount","File_FileName","File_ContentType"
20,"Simple Request App","Tutorial",1,93,"Completed",1,"tutorial",1,"00 Questetra","Test Request 2","2020-05-18 10:30:11","2020-05-18 10:34:48",,"60,000","README.txt","text/plain"
20,"Simple Request App","Tutorial",1,92,"Completed",1,"tutorial",1,"00 Questetra","Test Request 1","2020-05-18 10:28:28","2020-05-18 10:34:42",,"22,000","ques-kun.png","image/png"

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 20)”
  • Process End Date is in between 1st of April and 31st of May, 2020
  • Processes that have ended
  • Indicate Data Item of “Amount (Data number 0)” and “File(Data number 5)” on the search results

the XML will be the following.

<?xml version="1.0" encoding="UTF-8" ?>
<process-instance-criteria>
<process-model-info-id>20</process-model-info-id>
<end-date-from>2020-04-01</end-date-from>
<end-date-to>2020-05-31</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>5</data-definition-number>
<value></value>
<view></view>
</date>
</data>
</process-instance-criteria>

criteria is used also for Process searches in 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 (In this article, we select “Simple Request App” and add “Amount” and “File” to “Display items”).

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 XML data as a text file. In this article, we name the file as “process_criteria.txt”.

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"	"Token Current Position"	"Amount"	"File_FileName"	"File_ContentType"
20	"Simple Request App"	"Tutorial"	1	93	"Running"	1	"Tutorial"	1	"00 Questetra"	"Test Request 2"	"2020-05-18 10:30:11"		"Approve"	"60,000"	"README.txt"	"text/plain"
20	"Simple Request App"	"Tutorial"	1	92	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test Request 1"	"2020-05-18 10:28:28"	"2020-05-18 10:34:42"		"22,000"	"ques-kun.png"	"image/png"

To include Data Items in the result, you need to specify their Data Item numbers in criteria. In this article, we obtain criteria from Process search in Web UI. On the Process search page in Web UI, be sure to open the “Display items” area, check the Data Items to include, and then click the “Update” button to get the updated criteria.

In the same way, you can use /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)

"App ID","App Name","Category","Version","Process ID","Status","Start User ID","Start User","Start Organization ID","Start Organization","Title","Start Time","End Time","Token Current Position","Amount","File_FileName","File_ContentType"
20,"Simple Request App","Tutorial",1,93,"Running",1,"tutorial",1,"00 Questetra","Test Request 2","2020-05-18 10:30:11",,"Approve","60,000","README.txt","text/plain"
20,"Simple Request App","Tutorial",1,92,"Completed",1,"tutorial",1,"00 Questetra","Test Request 1","2020-05-18 10:28:28","2020-05-18 10:34:42",,"22,000","ques-kun.png","image/png"

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

{
  "count":2,
  "processInstances":[
    {
      "activeTokenNodeName":["Approve"],
      "data":{
        "0":{
          "dataType":"DECIMAL",
          "id":5784,
          "processDataDefinitionNumber":0,
          "subType":null,
          "value":"60,000",
          "viewOrder":4
        },
        "5":{
          "dataType":"FILE2",
          "id":5789,
          "processDataDefinitionNumber":5,
          "subType":null,
          "value":[
            {
              "contentType":"text\/plain",
              "id":5798,
              "image":false,
              "length":7,
              "lengthText":"7 bytes",
              "name":"README.txt",
              "processDataInstanceId":5789
            }
          ],
          "viewOrder":6
        }
      },
      "processInstanceDebug":false,
      "processInstanceEndDatetime":null,
      "processInstanceId":93,
      "processInstanceIdForView":"p93",
      "processInstanceInitQgroupId":1,
      "processInstanceInitQgroupName":"00 Questetra",
      "processInstanceInitQuserId":1,
      "processInstanceInitQuserName":"tutorial",
      "processInstanceSequenceNumber":2,
      "processInstanceStartDatetime":"2020-05-18T10:30:11+0900",
      "processInstanceState":"STARTED",
      "processInstanceTitle":"Test Request 2",
      "processModelInfoCategory":"Tutorial",
      "processModelInfoId":20,
      "processModelInfoName":"Simple Request App",
      "processModelVersion":1
    },
    {
      "activeTokenNodeName":null,
      "data":{
        "0":{
          "dataType":"DECIMAL",
          "id":5759,
          "processDataDefinitionNumber":0,
          "subType":null,
          "value":"22,000",
          "viewOrder":4
        },
        "5":{
          "dataType":"FILE2",
          "id":5764,
          "processDataDefinitionNumber":5,
          "subType":null,
          "value":[
            {
              "contentType":"image\/png",
              "id":5773,
              "image":true,
              "length":7236,
              "lengthText":"7.1 KB",
              "name":"ques-kun.png",
              "processDataInstanceId":5764
            }
          ],
          "viewOrder":6
        }
      },
      "processInstanceDebug":false,
      "processInstanceEndDatetime":"2020-05-18T10:34:42",
      "processInstanceId":92,
      "processInstanceIdForView":"p92",
      "processInstanceInitQgroupId":1,
      "processInstanceInitQgroupName":"00 Questetra",
      "processInstanceInitQuserId":1,
      "processInstanceInitQuserName":"tutorial",
      "processInstanceSequenceNumber":1,
      "processInstanceStartDatetime":"2020-05-18T10:28:28+0900",
      "processInstanceState":"ENDED",
      "processInstanceTitle":"Test Request 1",
      "processModelInfoCategory":"Tutorial",
      "processModelInfoId":20,
      "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://example.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. In this article, we save criteria for Task search as “workitem_criteria.txt” and specify it in the command. You cannot use “process_criteria.txt” which we saved for Process search in the previous section.

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"
20	"Simple Request App"	""	2	15	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test"	"2020-04-10 16:07:28"	"2020-04-10 17:37:41"	2	"Confirmation"	"Finished"		11	"Canarias"	2	"10 Management department"	"2020-04-10 16:07:44"	"2020-04-10 17:37:34"	"2020-04-10 17:37:34"	"2020-04-10 17:37:38"	"1,000"	"2020-04-10"
20	"Simple Request App"	""	2	15	"Completed"	1	"Tutorial"	1	"00 Questetra"	"TEST"	"2020-04-10 16:07:28"	"2020-04-10 17:37:41"	1	"Apply"	"Finished"		1	"Tutorial"	1	"00 Questetra"	"2020-04-10 16:07:28"	"2020-04-10 16:07:28"	"2020-04-10 16:07:28"	"2020-04-10 16:07:42"	"1,000"	"2020-04-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"
20,"Simple Request App","",2,15,"Completed",1,"Tutorial",1,"00 Questetra","Test","2020-04-10 16:07:28","2020-04-10 17:37:41",2,"Confirmation","Finished",,11,"Canarias",2,"10 Management department","2020-04-10 16:07:44","2020-04-10 17:37:34","2020-04-10 17:37:34","2020-04-10 17:37:38","1,000","2020-04-10"
20,"Simple Request App","",2,15,"Completed",1,"Tutorial",1,"00 Questetra","TEST","2020-04-10 16:07:28","2020-04-10 17:37:41",1,"Apply","Finished",,1,"Tutorial",1,"00 Questetra","2020-04-10 16:07:28","2020-04-10 16:07:28","2020-04-10 16:07:28","2020-04-10 16:07:42","1,000","2020-04-10"
...

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

{
  "count": 4,
  "workitems": [
    {
      "allocateDatetime": "2020-04-10T17:37:34+0900",
      "allocatedQgroupId": 2,
      "allocatedQgroupName": "10 Management department",
      "allocatedQuserId": 11,
      "allocatedQuserName": "Canarias",
      "offerDatetime": "2020-04-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": "2020-04-10",
          "viewOrder": 2
        }
      },
      "endDatetime": "2020-04-10T17:37:38+0900",
      "failType": null,
      "id": 2434,
      "nodeName": "Confirmation",
      "nodeNumber": 2,
      "processInstanceDebug": false,
      "processInstanceEndDatetime": "2020-04-10T17:37:41",
      "processInstanceId": 15,
      "processInstanceIdForView": "p15",
      "processInstanceInitQgroupId": 1,
      "processInstanceInitQgroupName": "00 Questetra",
      "processInstanceInitQuserId": 1,
      "processInstanceInitQuserName": "Tutorial",
      "processInstanceSequenceNumber": 2,
      "processInstanceStartDatetime": "2020-04-10T16:07:28+0900",
      "processInstanceState": "ENDED",
      "processInstanceTitle": "TEST",
      "processModelInfoCategory": "",
      "processModelInfoId": 20,
      "processModelInfoName": "Simple Request App",
      "processModelVersion": 2,
      "read": false,
      "starred": false,
      "startDatetime": "2020-04-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>20</process-model-info-id>
<end-date-from>2020-04-01</end-date-from>
<end-date-to>2020-05-31</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

1 thought on “Downloading Process and Task List Using Workflow API”

  1. Pingback: Download Process Files Using the Workflow API – Questetra Support

Comments are closed.

%d bloggers like this: