Deprecated
Visit the link below for the latest information
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 XML.
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.
criteria is XML data that specifies the search conditions. For example, the following search conditions will result in the XML below:
- 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
<?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 Google Chrome’s Inspect tool to retrieve the criteria used in the Web UI and use it to access the API 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.
On this page, open the Inspect tool by right-clicking anywhere on the web browser and selecting Inspect from the menu (or pressing Ctrl+Shift+I). The Inspection tool will appear, splitting the window. When you perform a 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 will select “Simple Request App” and add “Amount” and “File” to the Display items.)
The item displayed with the name “list?_dc={NUMBER}” is the request that has been sent.
Click on the item name to view the details. criteria is written in the Form Data section at the bottom.
Save this XML data as a text file. In this article, we will name the file “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 UTF-16 CSV format. This format is compatible with 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 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 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.csvThe 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 the 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 Task Data
As with Processes, you can retrieve Task information via the Workflow API. criteria is required, as with the Process search, and you can use it in the same way by switching the dropdown at the top right of the page from “Display at the level of processes” 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.txtEven 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 the place to look for criteria. In this article, we save criteria for the Task search as “workitem_criteria.txt” and specify it in the command. You cannot use the name “process_criteria.txt” which we saved 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 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,000" "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,000" "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,000",""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,000","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,000",
"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
Appendix: How to change the sorting rules of search results
By default, search results are sorted according to the following rules.
- Process search: descending order of Process Start time
- Task search: descending order of Task Offered time
To change these sorting rules, 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 |
See also
Downloading Process and Task Lists Using Workflow API (reportId)
Pingback: Downloading Process and Task Lists Using Workflow API (reportId) – Questetra Support