2022-05-30 / Questetra Developers Blog /

As discussed previously in the article regarding reportId, there is another method that can be used to download Process and Task data which utilizes criteria.

The following tasks must be performed by an account that has Data Viewer Authorization for the target Workflow App. You can check whether your account has the Data Viewer privileges in [Account Settings] > [Authorization].

To Download Process Data

The previous article explained how to search for Process data using the Workflow API and how to download this data in various formats, so please refer to that page for information on how to save filtered searches, etc.

Preparation of search parameters

As mentioned previously, 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

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

In criteria, specify the search conditions in JSON format. For example, the following search condition will be the following JSON data.

  • Processes of “Simple Request App (App ID 20)”
  • Process End Date is between the 1st and 31st of January, 2022
  • Processes that have ended
  • Indicate Data Item of “Amount (Data number 0)” and “File(Data number 5)” on the search results
  • Sort the search result by Start Date in descending order
{
  "processModelInfoId":2726,
  "processInstanceStartDateFrom":"2022-01-01",
  "processInstanceStartDateTo":"2022-01-31",
  "processInstanceState":["STARTED"],
  "fields":[
    {
      "type":"decimal",
      "number":0
    },
    {
      "type":"file",
      "number":5
    }
  ],
  "sortProperty":"processInstanceStartDatetime",
  "sortDirection":"DESC"
}

Save this JSON data as a text file. In this article, we will name the file “search_criteria.txt”.

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

Obtaining Process search results with curl command

Let’s send a request to /API/OR/ProcessInstance/listCsvUtf16 to get a list of Processes that meet the search criteria. The response of this API is returned in UTF-16 CSV format, which is compatible with Excel.

In Questetra BPM Suite, OAuth2 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 criteria@search_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 JSON 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@search_criteria.txt, the content of search_criteria.txt is passed to the parameter criteria.

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 results. Even if it is not specified in the criteria, items common to all processes (such as app ID) are included in the search results by default.

"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 their Data Item numbers in the criteria. You can confirm the Data Item Number on the Data Item Settings screen of the App Details.

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 returned responses 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

As with Processes, you can retrieve Task information via the Workflow API.

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@search_criteria.txt \
> --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. Specify the same file as before for criteria.

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 then import to Excel.

Below is an example of the result. Results after the third entry 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 (reportId)

%d bloggers like this: