2022-06-07 / Questetra Developers Blog /

There are two Web APIs 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. In this article I will show you how to download a list of Processes (instances) and Tasks via the Workflow API using the reportId function. By using the Workflow API you can create scripts that automatically download Process/Task data on a regular basis.

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 Process Data

Questetra BPM Suite has a process search function in its Web UI. For example, you can search by specifying the App and selecting the Data Items to be displayed, 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 a 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 will use the Simple Request App from the tutorial Creating a Travel Request App, after adding a File-type Data Item to it.

These search results can be obtained via the Workflow API. When downloaded, for example, in CSV (UTF-8) format, the following search results are returned from the 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","Test App",1,93,"Running",1,"tutorial",1,"00 Questetra","Test Request 2","2022-01-18 10:30:11",,"Approve","60.00","README.txt","text/plain"
20,"Simple Request App","Test App",1,92,"Completed",1,"tutorial",1,"00 Questetra","Test Request 1","2022-01-18 10:28:28","2022-01-18 10:34:42",,"22.00","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 the Web UI the download menu is located at the top of the search results.

Preparation of search parameters

There are two tools which can be used to specify and retrieve data via Questetra’s Workflow API; these are:

  • reportId
  • Criteria

In this article, I will discuss only the method that uses reportId. The explanation for using the criteria method can be found here.

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

  • start: specifies the starting position on the search results list
  • limit: specifies the maximum number of results to be obtained
  • Parameter that specifies the search conditions
    • reportId
    • criteria

Only one of either reportId or criteria will be used at a time, as they both perform the same function in this process.

For start (0 by default) and limit (1 by default, max. 1000), you just specify an appropriate number according to your purpose.

The reportId is a feature which can be used for specifying and retrieving saved searches for Process data in Questetra’s web UI.

When you use the Save List function to save the search conditions, the saved list is automatically assigned a reportId. This ID acts as a reference which can be used instead of criteria JSON to refer to Process search data.

In the Workflow section of Questetra go to the All Processes screen and in the filters section specify an App and an End Date using the dropdown menus.

A list of Processes related to the specified App will be displayed in that date range.

Click the “Save List” button and a window will appear where you can specify a name for the saved search.

As soon as the list is saved a reportId will be automatically assigned to it, which will be displayed in the URL.

The chosen List Name will now appear in the side menu in the [Others] section, so you can retrieve the saved search with only one click.

You can use reportId to express the list data in 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 it 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 'reportId=1234567' \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0'

In order to pass the URL encoding to the curl command, send each parameter as ‘key=value’ by the –data-urlencode option. For short parameters, it is better to embed them directly in the command as ‘key=value’.

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

Also, it is possible to perform Basic Authentication with the -u option in curl command. Write the email address and password 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"	"Test App"	1	93	"Running"	1	"Tutorial"	1	"00 Questetra"	"Test Request 2"	"2022-01-18 10:30:11"		"Approve"	"60.00"	"README.txt"	"text/plain"
20	"Simple Request App"	"Test App"	1	92	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test Request 1"	"2022-01-18 10:28:28"	"2022-01-18 10:34:42"		"22.00"	"ques-kun.png"	"image/png"

To include Data Items in the result, you need to specify these Data Items in the Search conditions when they are saved and the reportId is generated. In this article, we obtain the reportId from a Process search in the Web UI. On the Process search page in the Web UI be sure to open the “Display items” area, check the Data Items to be included, and then click the “Update Saved List” button to update the saved conditions to which the reportId has been assigned.

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","Test App",1,93,"Running",1,"tutorial",1,"00 Questetra","Test Request 2","2022-01-18 10:30:11",,"Approve","60.00","README.txt","text/plain"
20,"Simple Request App","Test App",1,92,"Completed",1,"tutorial",1,"00 Questetra","Test Request 1","2022-01-18 10:28:28","2022-01-18 10:34:42",,"22.00","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.00",
          "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":"2022-01-18T10:30:11+0900",
      "processInstanceState":"STARTED",
      "processInstanceTitle":"Test Request 2",
      "processModelInfoCategory":"Test App",
      "processModelInfoId":20,
      "processModelInfoName":"Simple Request App",
      "processModelVersion":1
    },
    {
      "activeTokenNodeName":null,
      "data":{
        "0":{
          "dataType":"DECIMAL",
          "id":5759,
          "processDataDefinitionNumber":0,
          "subType":null,
          "value":"22.00",
          "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":"2022-01-18T10:34:42",
      "processInstanceId":92,
      "processInstanceIdForView":"p92",
      "processInstanceInitQgroupId":1,
      "processInstanceInitQgroupName":"00 Questetra",
      "processInstanceInitQuserId":1,
      "processInstanceInitQuserName":"tutorial",
      "processInstanceSequenceNumber":1,
      "processInstanceStartDatetime":"2022-01-18T10:28:28+0900",
      "processInstanceState":"ENDED",
      "processInstanceTitle":"Test Request 1",
      "processModelInfoCategory":"Test App",
      "processModelInfoId":20,
      "processModelInfoName":"Simple Request App",
      "processModelVersion":1
    }
  ]
}

To Download Task Data

Task information can be retrieved from the Workflow API in the same way as process information. As with the process search criteria is required, but you can search in the same way by switching to Operated Tasks in the left menu and opening the task search page.

For Task Data there are two special values which can be specified as a reportId. These are:

  • ALLOCATED – My Tasks
  • OFFERED – Offered Tasks

So for example, a URL such as the following will return data of the Tasks listed in the “Offered” list. 

https://****.questetra.net/API/OR/Workitem/list?reportId=OFFERED

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 'reportId=1234567' \
> --data-urlencode 'limit=10' \
> --data-urlencode 'start=0' > ~/Desktop/output.txt

Even though the target of the search has changed from Processes to Tasks, the parameters are the same as with the Process search. Note that the Task search page is where you configure a search condition and save it to obtain another reportId. In this article, we will use the newly obtained reportId for the Task search by specifying it in the command. You cannot use the same reportId which we used for the 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"	"File_FileName"	"File_ContentType"
20	"Simple Request App"	"Test App"	2	15	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test Request 1"	"2022-01-10 16:07:28"	"2022-01-10 17:37:41"	2	"Confirmation"	"Finished"		11	"Canarias"	2	"10 Management department"	"2022-01-10 16:07:44"	"2022-01-10 17:37:34"	"2022-01-10 17:37:34"	"2022-01-10 17:37:38"	"22.00"	"ques-kun.png"	"image/png"
20	"Simple Request App"	"Test App"	2	15	"Completed"	1	"Tutorial"	1	"00 Questetra"	"Test Request 1"	"2022-01-10 16:07:28"	"2022-01-10 17:37:41"	1	"Apply"	"Finished"		1	"Tutorial"	1	"00 Questetra"	"2022-01-10 16:07:28"	"2022-01-10 16:07:28"	"2022-01-10 16:07:28"	"2022-01-10 16:07:42"	"22.00"	"ques-kun.png"	"image/png"
...

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","Test App",2,15,"Completed",1,"Tutorial",1,"00 Questetra","Test Request 1","2022-01-10 16:07:28","2022-01-10 17:37:41",2,"Confirmation","Finished",,11,"Canarias",2,"10 Management department","2022-01-10 16:07:44","2022-01-10 17:37:34","2022-01-10 17:37:34","2022-01-10 17:37:38","22.00",""ques-kun.png","image/png"
200,"Simple Request App","Test App",2,15,"Completed",1,"Tutorial",1,"00 Questetra","Test Request 1","2022-01-10 16:07:28","2022-01-10 17:37:41",1,"Apply","Finished",,1,"Tutorial",1,"00 Questetra","2022-01-10 16:07:28","2022-01-10 16:07:28","2022-01-10 16:07:28","2022-01-10 16:07:42","22.00","ques-kun.png","image/png"
...

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

{
  "count": 4,
  "workitems": [
    {
      "allocateDatetime": "2022-01-10T17:37:34+0900",
      "allocatedQgroupId": 2,
      "allocatedQgroupName": "10 Management department",
      "allocatedQuserId": 11,
      "allocatedQuserName": "Canarias",
      "offerDatetime": "2022-01-10T16:07:44+0900",
      "data": {
        "0": {
          "dataType": "DECIMAL",
          "id": 2424,
          "processDataDefinitionNumber": 0,
          "subType": null,
          "value": "22.00",
          "viewOrder": 1
        },
        "1": {
          "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
        }
      },
      "endDatetime": "2022-01-10T17:37:38+0900",
      "failType": null,
      "id": 2434,
      "nodeName": "Confirmation",
      "nodeNumber": 2,
      "processInstanceDebug": false,
      "processInstanceEndDatetime": "2022-01-10T17:37:41",
      "processInstanceId": 15,
      "processInstanceIdForView": "p15",
      "processInstanceInitQgroupId": 1,
      "processInstanceInitQgroupName": "00 Questetra",
      "processInstanceInitQuserId": 1,
      "processInstanceInitQuserName": "Tutorial",
      "processInstanceSequenceNumber": 2,
      "processInstanceStartDatetime": "2022-01-10T16:07:28+0900",
      "processInstanceState": "ENDED",
      "processInstanceTitle": "Test Request 1",
      "processModelInfoCategory": "Test App",
      "processModelInfoId": 20,
      "processModelInfoName": "Simple Request App",
      "processModelVersion": 2,
      "read": false,
      "starred": false,
      "startDatetime": "2022-01-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 where you need a backup for an audit, or you want to analyze the business situation.

See also

Downloading Process and Task Lists Using Workflow API (criteria-JSON)

%d bloggers like this: