Please rate how useful you found this document: 
Average: 2 (3 votes)

Overview

ProcessMaker provides connection to other applications though REST API. To see more information about REST API in ProcessMaker, for example registering a new application or generating an access token, please follow this wiki page. In this wiki page we are going to describe the endpoints in the sections below that are used to obtain information about cases and control when running cases.

Contents: [hide]

Filters For Listing Cases

Regarding to the case status or search, the following endpoints return a list of cases:

Any of those endpoints return fifteen cases by default and they are sort by case number, which means that cases created recently display first. Aditionally, diferent GET parameters could be included in the URL.

Shared Cases URL Parameters

The table in the section below table describes details about the shared URL parameters when listing cases. The other parameters are explained in every endpoint section.

Parameter Description Default value Example
caseNumber={integer} Receives an integer that is the Number of the case. 0 /api/1.0/workflow/home/todo?caseNumber=297
process={integer} Receives an integer that is the Process UID. 0 /api/1.0/workflow/home/todo?process=1234567890
task={integer} Receives an integer that is the Task UID. 0 /api/1.0/workflow/home/todo?task=1234567890
limit={integer} Receives an integer with the limit number. 0 /api/1.0/workflow/home/todo?limit=5
offset={integer} Receives an integer with the offset number. 0 /api/1.0/workflow/home/todo?offset=5
caseTitle={string} Receives a case title string. /api/1.0/workflow/home/todo?caseTitle=CaseTitle
reviewStatus={string}
Available as of ProcessMaker 3.7.7		 Receives a string with the review status such as READ, UNREAD or Empty. The reviewStatus indicates whether the assigned user reviewed the case or not. /api/1.0/workflow/home/todo?reviewStatus=READ

Calling /home/{case_status} endpoints

After calling a GET /home/{case_status} endpoint, decode the JSON string returned by the endpoint with a function such as JSON.parse(), eval() in JavaScript or json_decode() in PHP.

It returns an object with a data array containing the case objects and a total with the total cases number value.

Case Object

The GET endpoints which return cases enclose the information about each case in the following case object:

Element Description Example
{ Begin case object.
APP_NUMBER The Case Number, which counts cases in the workspace, starting from 1. 220
DEL_TITLE The delegation process title. #220
PRO_TITLE The title for the case process. PROCESS EMAIL LINK TO CASE
TAS_TITLE The title for the current case task. Path2 Task
USR_USERNAME john
USR_FIRSTNAME The username for the current user in the process. John
USR_LASTNAME The user last name for the current user in the process. Doe
DEL_TASK_DUE_DATE Datetime in "YYYY-MM-DD HH:MM:SS" format when the current task is due (scheduled to be completed). 2021-03-03 09:00:30
DEL_DELEGATE_DATE Datetime in "YYYY-MM-DD HH:MM:SS" format when case was routed to the current task. 2021-03-02 09:00:30
DEL_PRIORITY The case's delegation priority index which can be "VERY LOW" (1), "LOW" (2), "NORMAL" (3), "HIGH" (4) and "VERY HIGH" (5). 3
DEL_PREVIOUS The previous delegation index. 2
APP_UID Unique ID of case. 684564696603e44c4e4a902023288322
DEL_INDEX Delegation index of case, which counts tasks executed in the case, starting from 1. 4
PRO_UID Unique ID of the case's process. 3574616336037a51b480613060686372
TAS_UID Unique ID of current task in case. 2504790786037a51b7e6654038512745
DEL_PRIORITY_LABEL The case's delegation priority label which can be "VERY LOW" (1), "LOW" (2), "NORMAL" (3), "HIGH" (4) and "VERY HIGH" (5). NORMAL
TAS_COLOR Color of the current task diferenced by status. 2
TAS_COLOR_LABEL Color label of the current task diferenced by status. red
TAS_STATUS Current status of the task. OVERDUE
DELAY Current task delay that displays in Days, Hours and seconds. 173 Day(s) 03 Hr(s) 02 min 05 s
DEL_TASK_DUE_DATE_LABEL Date in "MM.DD.YY" format when the delegation task started with the due. 03.03.21
DEL_DELEGATE_DATE_LABEL Date in "MM.DD.YY" format when the task was delegated. 03.02.21
SEND_BY_INFO Object with the previous delegation index and the user tooltip array. {"del_previous": 2, "user_tooltip": []}
} End case object.

Returning a list of cases

The GET endpoints which return a list of cases, return an object with a data array of case objects and a total value with the following structure:

{
    "data": [
          {   // first case object
            "APP_NUMBER": "298",
            ...
          },
          {   // second case object
            "APP_NUMBER": "297",
            ...
          }
          ... // additional case objects
        ],
    "total": 90

Reading a list of cases with JavaScript:

var req = new XMLHttpRequest();
req.open("GET", "https://example.com/api/1.0/workflow/home/todo", true);
req.setRequestHeader("Authorization", "Bearer " + accessToken);

req.onreadystatechange = function() {
   if (req.readyState==4 && req.status==200) {  //if a successful request
      //use JSON.parse() to decode string if browser supports it:
      var reqtData = (JSON) ? JSON.parse(req.responseText) : eval(req.responseText);
      var aCasesTotal = reqData.total;
      var aCases = reqData.data;

      //loop through array of cases and print when each one is due in the <body>
      for (var i = 0; i < aCases.length; i++) {
         var p = document.createElement('p');
         p.innerHTML = "Case number '" + aCases[i].APP_NUMBER + "' in task '" + aCases[i].TAS_TITLE +
            "' is due " + aCases[i].DEL_TASK_DUE_DATE_LABEL + ".";
         document.body.appendChild(p);
      }
   }
};
req.send(null);

Reading a list of cases with PHP:

$ch = curl_init("https://example.com/api/1.0/workflow/cases");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$reqData = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($statusCode == 200) { //if successful request
   //loop through array of cases and print when each one is due:
   $aCasesTotal = $reqData->total;
   $aCases = $reqData->data;
   foreach ($aCases as $oCase) {
      print "<p>Case number '{$oCase->APP_NUMBER}' in task '{$oCase->TAS_TITLE}' is due {$oCase->DEL_TASK_DUE_DATE_LABEL}.</p>\n";
   }
}

Get To Do Cases: GET /home/todo

This endpoint get the list of the To Do cases for the logged on user. The following is the syntax when calling the endpoint:

GET /api/1.0/{workspace}/home/todo?{param1=value}&{param2=value2}

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/home/todo
filters For further information, check the Filters for Listing To Do cases section. /api/1.0/workflow/home/todo?limit=7

Result:

When calling the endpoint successfully, the HTTP status code is set to 200 and an object with a data array of case objects and a total value is returned. Check the example below.

{
    "data": [
        {
            "APP_NUMBER": 298,
            "DEL_TITLE": "# 298",
            "PRO_TITLE": "PMCORE-3126",
            "TAS_TITLE": "t1 4h",
            "USR_USERNAME": null,
            "USR_FIRSTNAME": null,
            "USR_LASTNAME": null,
            "DEL_TASK_DUE_DATE": "2021-08-18 15:02:33",
            "DEL_DELEGATE_DATE": "2021-08-17 15:02:33",
            "DEL_PRIORITY": "3",
            "DEL_PREVIOUS": 4,
            "APP_UID": "576293895611c0533f38754023459753",
            "DEL_INDEX": 5,
            "PRO_UID": "932791136611be1231ef8f9057005581",
            "TAS_UID": "icte-6801611be14eab3ed4087280461",
            "DEL_PRIORITY_LABEL": "NORMAL",
            "TAS_COLOR": 2,
            "TAS_COLOR_LABEL": "red",
            "TAS_STATUS": "OVERDUE",
            "DELAY": " 5 Day(s) 06 Hr(s) 17 min 56 s",
            "DEL_TASK_DUE_DATE_LABEL": "08.18.21",
            "DEL_DELEGATE_DATE_LABEL": "08.17.21",
            "SEND_BY_INFO": {
                "del_previous": 4,
                "user_tooltip": []
            }
        }, {
            ...
        }
    ],
        "total": 85
}

If an error occurred, then the HTTP status code is set with the 400 code or above and an error object is returned. Check the example below.

{
    "error": {
        "code": 400,
        "message": "Bad Request: Invalid value specified for `limit`. Expecting integer value"
    }
}

Filters For Listing Todo Cases

In addition to the filter parameters described in a previous section, these are the filters when working with To Do cases:

Parameter Description Default value Example
delegateFrom={string} Receives a delegate from string value. /api/1.0/workflow/home/todo?delegateFrom=DelegateFrom
delegateTo={string} Receives a delegate to string value. /api/1.0/workflow/home/todo?delegateTo=DelegateTo

JavaScript Example

This example prints a list of To Do cases which are overdue. It compares the due date of the current task with the current datetime. The two datetimes are instantiating as Date() objects so they can be compared. (Note that the date comparison will only be exact if the time of the local computer is the same as the time on the ProcessMaker server.) In order to instantiate the due date as a Date object, the replace(/-/g, ' ')) method is used to convert its value from YYYY-MM-DD HH:MM:SS to YYYY MM DD HH:MM:SS.

var apiServer = "https:// example.com"; //set to address of your ProcessMaker server
var accessToken = getCookie("access_token"); // custom function to get a stored cookie
if (!accessToken) {
   accessToken = getAccessToken(); //custom function to get a new access token
}

var req = new XMLHttpRequest();
req.open("GET", apiServer + "/api/1.0/workflow/home/todo", true);
req.setRequestHeader("Authorization", "Bearer " + accessToken);

req.onreadystatechange = function() {
   if (req.readyState == 4 && req.status == 200) {  //if a successful request
      //use JSON.parse() to decode response text if the web browser supports it:
     
      var getData = (JSON) ? JSON.parse(req.responseText) : eval(req.responseText);
      var aCasesTotal = getData.total;
      var aCases = getData.data;

      //loop through array of cases and print each one which is overdue in the <body>
      for (var i = 0; i < aCases.length; i++) {
         var dueDate = new Date(aCases[i].DEL_TASK_DUE_DATE.replace(/-/g, ' '));
         var currentDate = new Date(); // this may need to be adjusted to match time on server
         if (dueDate.getTime() < currentDate.getTime()) {
            var p = document.createElement('p');
            p.innerHTML = "Case number '" + aCases[i].APP_NUMBER + "' in task '" + aCases[i].TAS_TITLE +
               "' was due " + aCases[i].DEL_TASK_DUE_DATE + ".";
            document.body.appendChild(p);
         }
      }
   }
   else if (req.readyState == 4 && req.status != 0) {
      var oErr = (JSON) ? JSON.parse(req.responseText) : eval(req.responseText);
      if (oErr)
         alert("Error code: " + oErr.error.code + "\nMessage: " + oErr.error.message);
      else
         alert("HTTP status error: " + req.status);
   }
}
req.send(null);

The above JavaScript code should add text to the bottom of the web page, such as:

Case '#12' in task 'Company protocol training' was due 2021-02-05 17:00:00.
Case '#10' in task 'Company protocol training' was due 2021-02-02 13:16:17.
Case '#7' in task 'Practice safety with trainer' was due 2021-02-02 11:15:14.
Case '#5' in task 'Written safety test' was due 2021-01-30 12:41:35.
Case '#5' in task 'Practice safety with trainer' was due 2021-01-30 12:41:36.
Case '#3' in task 'Practice safety with trainer' was due 2021-01-30 09:45:10.

PHP Example

This example prints a list of To Do cases which are overdue. It compares the due date of the current task with the current datetime which is obtained using the date('Y-m-d H:i:s') function. Note that it compares the two dates as strings, which works because both are in standard YYYY-MM-DD HH:MM:SS format.

$apiServer = "https://example.com"; //set to your ProcessMaker address
$accessToken = isset($_COOKIE['access_token']) ? $_COOKIE['access_token'] : getAccessToken(); // custom function to get a new access token

$ch = curl_init($apiServer . "/api/1.0/workflow/home/todo");
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$aCases = json_decode(curl_exec($ch));

$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($statusCode != 200) {
   if (isset ($aCases) and isset($aCases->error))
      print "Error code: {$aCases->error->code}\nMessage: {$aCases->error->message}\n";
   else
      print "Error: HTTP status code: $statusCode\n";
}
else {
   print "<font color=red>Overdue Cases:</font><br>\n";
   $zCases = $aCases->data;
   foreach ($zCases as $oCase) {
      //if the due date is before the current datetime, then print it.
      if ($oCase->DEL_TASK_DUE_DATE < date('Y-m-d H:i:s')) {
         print "Case '{$oCase->app_title}' was due on {$oCase->DEL_TASK_DUE_DATE}.<br>\n";
      }
   }
}

The above PHP code print text, such as:

<font color="red">Overdue Cases:</font>
Case '#12' was due on 2021-02-05 17:00:00.
Case '#10' was due on 2021-02-02 13:16:17.
Case '#7' was due on 2021-02-02 11:15:14.
Case '#5' was due on 2021-01-30 12:41:35.
Case '#5' was due on 2021-01-30 12:41:36.
Case '#3' was due on 2021-01-30 09:45:10.

Get Draft Cases: GET /home/draft

This endpoint get the list of the To Do cases for the logged on user. The following is the syntax when calling the endpoint:

GET /api/1.0/{workspace}/home/draft?{param1=value}&{param2=value2}

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/home/draft
filters See Filters for Listing draft cases. /api/1.0/workflow/home/draft?limit=1

Result:

When calling the endpoint successfully, the HTTP status code is set to 200 and an object with a data array of case objects and a total value is returned. Check the example below.

{
    "data": [
        {
            "APP_NUMBER": 172,
            "DEL_TITLE": "# 172",
            "PRO_TITLE": "PMCORE-985: Replicate Bug Notifications",
            "TAS_TITLE": "Task 4",
            "DEL_TASK_DUE_DATE": "2021-02-03 13:34:54",
            "DEL_DELEGATE_DATE": "2021-02-02 13:34:54",
            "DEL_PRIORITY": "3",
            "DEL_PREVIOUS": 1,
            "APP_UID": "42985128560199b4a8b7f96064834917",
            "DEL_INDEX": 2,
            "PRO_UID": "6516103415d541866d26b15085318914",
            "TAS_UID": "619746171601981e4a58e55072232126",
            "DEL_PRIORITY_LABEL": "NORMAL",
            "TAS_COLOR": 2,
            "TAS_COLOR_LABEL": "red",
            "TAS_STATUS": "OVERDUE",
            "DELAY": " 201 Day(s) 07 Hr(s) 48 min 23 s",
            "DEL_TASK_DUE_DATE_LABEL": "02.03.21",
            "DEL_DELEGATE_DATE_LABEL": "02.02.21",
            "SEND_BY_INFO": {
                "del_previous": 1,
                "user_tooltip": {
                    "usr_id": 1,
                    "usr_username": "admin",
                    "usr_firstname": "Administrator",
                    "usr_lastname": "admin",
                    "usr_email": "admin@processmaker.com",
                    "usr_position": "Administrator"
                }
            }
        }, {
            ...
        }
    ],
    "total": 9
}

If an error occurred, then the HTTP status code is set with the 400 code or above and an error object is returned. Check the example below.

{
    "error": {
        "code": 400,
        "message": "Bad Request: Invalid value specified for `limit`. Expecting integer value"
    }
}

Filters For Listing Draft Cases

To see more details, check the filter parameters section.

Get Unassigned Cases: GET /home/unassigned

This endpoint get the list of the Unassigned cases for the logged on user. The following is the syntax when calling the endpoint:

GET /api/1.0/{workspace}/home/unassigned?{param1=value}&{param2=value2}

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/home/unassigned
filters For further information, check the Filters for Listing Unassigned cases section. /api/1.0/workflow/home/unassigned?limit=7

Result:

When calling the endpoint successfully, the HTTP status code is set to 200 and an object with a data array of case objects and a total value is returned. Check the example below.

{
    "data": [
        {
            "APP_NUMBER": 298,
            "DEL_TITLE": "# 298",
            "PRO_TITLE": "PMCORE-3126",
            "TAS_TITLE": "t1 4h",
            "USR_USERNAME": null,
            "USR_FIRSTNAME": null,
            "USR_LASTNAME": null,
            "DEL_TASK_DUE_DATE": "2021-08-18 15:02:33",
            "DEL_DELEGATE_DATE": "2021-08-17 15:02:33",
            "DEL_PRIORITY": "3",
            "DEL_PREVIOUS": 4,
            "APP_UID": "576293895611c0533f38754023459753",
            "DEL_INDEX": 5,
            "PRO_UID": "932791136611be1231ef8f9057005581",
            "TAS_UID": "icte-6801611be14eab3ed4087280461",
            "DEL_PRIORITY_LABEL": "NORMAL",
            "TAS_COLOR": 2,
            "TAS_COLOR_LABEL": "red",
            "TAS_STATUS": "OVERDUE",
            "DELAY": " 5 Day(s) 06 Hr(s) 17 min 56 s",
            "DEL_TASK_DUE_DATE_LABEL": "08.18.21",
            "DEL_DELEGATE_DATE_LABEL": "08.17.21",
            "SEND_BY_INFO": {
                "del_previous": 4,
                "user_tooltip": []
            }
        }, {
            ...
        }
    ],
        "total": 85
}

If an error occurred, then the HTTP status code is set with the 400 code or above and an error object is returned. Check the example below.

{
    "error": {
        "code": 400,
        "message": "Bad Request: Invalid value specified for `limit`. Expecting integer value"
    }
}

Filters For Listing Todo Cases

In addition to the filter parameters described in a previous section, these are the filters when working with Unassigned cases:

Parameter Description Default value Example
delegateFrom={string} Receives a delegate from string value. /api/1.0/workflow/home/unassigned?delegateFrom=DelegateFrom
delegateTo={string} Receives a delegate to string value. /api/1.0/workflow/home/unassigned?delegateTo=DelegateTo

Get Paused Cases: GET /home/paused

This endpoint get the list of the Paused cases for the logged on user. The following is the syntax when calling the endpoint:

GET /api/1.0/{workspace}/home/paused?{param1=value}&{param2=value2}

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/home/paused
filters For further information, check the Filters for Listing Paused cases section. /api/1.0/workflow/home/paused?limit=7

Result:

When calling the endpoint successfully, the HTTP status code is set to 200 and an object with a data array of case objects and a total value is returned. Check the example below.

{
    "data": [
        {
            "APP_NUMBER": 298,
            "DEL_TITLE": "# 298",
            "PRO_TITLE": "PMCORE-3126",
            "TAS_TITLE": "t1 4h",
            "USR_USERNAME": null,
            "USR_FIRSTNAME": null,
            "USR_LASTNAME": null,
            "DEL_TASK_DUE_DATE": "2021-08-18 15:02:33",
            "DEL_DELEGATE_DATE": "2021-08-17 15:02:33",
            "DEL_PRIORITY": "3",
            "DEL_PREVIOUS": 4,
            "APP_UID": "576293895611c0533f38754023459753",
            "DEL_INDEX": 5,
            "PRO_UID": "932791136611be1231ef8f9057005581",
            "TAS_UID": "icte-6801611be14eab3ed4087280461",
            "DEL_PRIORITY_LABEL": "NORMAL",
            "TAS_COLOR": 2,
            "TAS_COLOR_LABEL": "red",
            "TAS_STATUS": "OVERDUE",
            "DELAY": " 5 Day(s) 06 Hr(s) 17 min 56 s",
            "DEL_TASK_DUE_DATE_LABEL": "08.18.21",
            "DEL_DELEGATE_DATE_LABEL": "08.17.21",
            "SEND_BY_INFO": {
                "del_previous": 4,
                "user_tooltip": []
            }
        }, {
            ...
        }
    ],
        "total": 85
}

If an error occurred, then the HTTP status code is set with the 400 code or above and an error object is returned. Check the example below.

{
    "error": {
        "code": 400,
        "message": "Bad Request: Invalid value specified for `limit`. Expecting integer value"
    }
}

Filters For Listing Paused Cases

In addition to the filter parameters described in a previous section, these are the filters when working with Paused cases:

Parameter Description Default value Example
delegateFrom={string} Receives a delegate from string value. /api/1.0/workflow/home/paused?delegateFrom=DelegateFrom
delegateTo={string} Receives a delegate to string value. /api/1.0/workflow/home/paused?delegateTo=DelegateTo

Get Participated Cases: GET /home/mycases

This endpoint get the list of the Participated cases for the logged on user. The following is the syntax when calling the endpoint:

GET /api/1.0/{workspace}/home/mycases?{param1=value}&{param2=value2}

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/home/mycases
filters For further information, check the Filters for Listing Participated cases section. /api/1.0/workflow/home/mycases?limit=7

Result:

When calling the endpoint successfully, the HTTP status code is set to 200 and an object with a data array of case objects and a total value is returned. Check the example below.

{
    "data": [
        {
            "APP_NUMBER": 298,
            "DEL_TITLE": "# 298",
            "PRO_TITLE": "PMCORE-3126",
            "TAS_TITLE": "t1 4h",
            "USR_USERNAME": null,
            "USR_FIRSTNAME": null,
            "USR_LASTNAME": null,
            "DEL_TASK_DUE_DATE": "2021-08-18 15:02:33",
            "DEL_DELEGATE_DATE": "2021-08-17 15:02:33",
            "DEL_PRIORITY": "3",
            "DEL_PREVIOUS": 4,
            "APP_UID": "576293895611c0533f38754023459753",
            "DEL_INDEX": 5,
            "PRO_UID": "932791136611be1231ef8f9057005581",
            "TAS_UID": "icte-6801611be14eab3ed4087280461",
            "DEL_PRIORITY_LABEL": "NORMAL",
            "TAS_COLOR": 2,
            "TAS_COLOR_LABEL": "red",
            "TAS_STATUS": "OVERDUE",
            "DELAY": " 5 Day(s) 06 Hr(s) 17 min 56 s",
            "DEL_TASK_DUE_DATE_LABEL": "08.18.21",
            "DEL_DELEGATE_DATE_LABEL": "08.17.21",
            "SEND_BY_INFO": {
                "del_previous": 4,
                "user_tooltip": []
            }
        }, {
            ...
        }
    ],
        "total": 85
}

If an error occurred, then the HTTP status code is set with the 400 code or above and an error object is returned. Check the example below.

{
    "error": {
        "code": 400,
        "message": "Bad Request: Invalid value specified for `limit`. Expecting integer value"
    }
}

Filters For Listing Participated Cases

In addition to the filter parameters described in a previous section, these are the filters when working with Participated cases:

Parameter Description Default value Example
filterCases={string} Receives a filter case string value. /api/1.0/workflow/home/mycases?filterCases=filterCases
filter={string} Receives a filter string value. /api/1.0/workflow/home/mycases?filter=filter
caseStatus={string} Receives a case status string value. /api/1.0/workflow/home/mycases?caseStatus=caseStatus
startCaseFrom={string} Receives a start case from date in string format. /api/1.0/workflow/home/mycases?startCaseFrom=startCaseFrom
startCaseTo={string} Receives a start case to date in string format. /api/1.0/workflow/home/mycases?startCaseTo=startCaseTo
finishCaseFrom={string} Receives a finish case from date in string format. /api/1.0/workflow/home/mycases?finishCaseFrom=01-01-2021
finishCaseTo={string} Receives a finish case to date in string format. /api/1.0/workflow/home/mycases?finishCaseTo=01-01-2021

Get Searched Cases: GET /home/search

This endpoint get the list of the Searched cases for the logged on user. The following is the syntax when calling the endpoint:

GET /api/1.0/{workspace}/home/search?{param1=value}&{param2=value2}

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/home/search
filters For further information, check the Filters for Listing Searched cases section. /api/1.0/workflow/home/search?limit=7

Result:

When calling the endpoint successfully, the HTTP status code is set to 200 and an object with a data array of case objects and a total value is returned. Check the example below.

{
    "data": [
        {
            "APP_NUMBER": 207,
            "DEL_TITLE": "#207",
            "PRO_TITLE": "PMCORE-2838: Populate multiple file grid",
            "APP_STATUS": "DRAFT",
            "APP_CREATE_DATE": "2021-02-17 13:38:08",
            "APP_FINISH_DATE": null,
            "APP_UID": "941231572602d62902fb000023298879",
            "PRO_UID": "64520145960218deb33e252044547615",
            "APP_CREATE_DATE_LABEL": "02.17.21",
            "APP_FINISH_DATE_LABEL": null,
            "DURATION": " 187 Day(s) 08 Hr(s) 45 min 53 s",
            "CASE_NOTES_COUNT": 0,
            "DEL_INDEX": 1,
            "TAS_UID": "66043584360218e88439bb4025779674",
            "THREAD_TASKS": [
                {
                    "tas_uid": "66043584360218e88439bb4025779674",
                    "tas_title": "Task 1",
                    "user_id": 1,
                    "due_date": "2021-02-18 13:38:08",
                    "delay": " 186 Day(s) 08 Hr(s) 45 min 53 s",
                    "tas_color": 2,
                    "tas_color_label": "red",
                    "tas_status": "OVERDUE",
                    "unassigned": false,
                    "user_tooltip": {
                        "usr_id": 1,
                        "usr_username": "admin",
                        "usr_firstname": "Administrator",
                        "usr_lastname": "admin",
                        "usr_email": "admin@processmaker.com",
                        "usr_position": "Administrator"
                    }
                }
            ],
            "THREAD_USERS": [
                {
                    "user_tooltip": {
                        "usr_id": 1,
                        "usr_username": "admin",
                        "usr_firstname": "Administrator",
                        "usr_lastname": "admin",
                        "usr_email": "admin@processmaker.com",
                        "usr_position": "Administrator"
                    },
                    "user_id": 1,
                    "usr_username": "admin",
                    "usr_lastname": "admin",
                    "usr_firstname": "Administrator"
                }
            ],
            "THREAD_TITLES": [
                {
                    "del_id": 410,
                    "del_index": 1,
                    "thread_title": "# 207"
                }
            ]
        }
    ],
    "total": 0
}

If an error occurred, then the HTTP status code is set with the 400 code or above and an error object is returned. Check the example below.

{
    "error": {
        "code": 400,
        "message": "Bad Request: Invalid value specified for `limit`. Expecting integer value"
    }
}

Filters For Listing Searched Cases

In addition to the filter parameters described in a previous section, these are the filters when working with Searched cases:

Parameter Description Default value Example
filterCases={string} Receives a filter case string value. /api/1.0/workflow/home/search?filterCases=filterCases
caseStatuses={string} Receives a case status string value. /api/1.0/workflow/home/search?caseStatus=caseStatuses
startCaseFrom={string} Receives a start case from date in string format. /api/1.0/workflow/home/search?startCaseFrom=startCaseFrom
startCaseTo={string} Receives a start case to date in string format. /api/1.0/workflow/home/search?startCaseTo=startCaseTo
finishCaseFrom={string} Receives a finish case from date in string format. /api/1.0/workflow/home/search?finishCaseFrom=01-01-2021
finishCaseTo={string} Receives a finish case to date in string format. /api/1.0/workflow/home/search?finishCaseTo=01-01-2021
category={string} Receives a category string value. /api/1.0/workflow/home/search?category=category
user={string} Receives a username string value. /api/1.0/workflow/home/search?user=myUser
userCompleted={string} Receives the user that completed the process string value. /api/1.0/workflow/home/search?userCompleted=myUser
userStarted={string} Receives a the user that started the process string value. /api/1.0/workflow/home/search?userStarted=myUser

Get Case Information: GET /cases/{app_uid}

Get Information about a specified case.

Permission:

As of ProcessMaker 3.3.0, if users do not participate in the case, they must have Process Permissions like the Summary Form or ALL.

Structure:

GET /api/1.0/{workspace}/cases/{app_uid}

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/51382566154f7180953b5e1028461947
{app_uid} The unique ID of the case to get information about. /api/1.0/workflow/cases/51382566154f7180953b5e1028461947

Result:

If a successful, then the HTTP status code is set to 200 and the following information about the case and its current task(s) are returned. For example:

{
   "app_uid": "36722263554ca70b82c52e8020802754",
   "app_number": "5",
   "app_name": "#5",
   "app_status": "TO_DO",
   "app_init_usr_uid": "00000000000000000000000000000001",
   "app_init_usr_username": "Administrator",
   "pro_uid": "35648267754ca36d119ecc1014698225",
   "pro_name": "Safety training course",
   "app_create_date": "2015-01-29 12:41:12",
   "app_update_date": "2015-01-29 13:21:55",
   "current_task":
      (
         {
            "usr_uid": "00000000000000000000000000000001",
            "usr_name": "Administrator",
            "tas_uid": "89626647354ca3c43743e66000804527",
            "tas_title": "Written safety test",
            "del_index":  2,
            "del_thread": 2,
            "del_thread_status": "OPEN"
         },
         {
            "usr_uid": "00000000000000000000000000000001",
            "usr_name": "Administrator",
            "tas_uid": "60687790754ca3c434b57d5092245736",
            "tas_title": "Practice safety with trainer",
            "del_index": 3,
            "del_thread": 3,
            "del_thread_status": "OPEN"
         }
      )
}

If an error occurred, then the HTTP status code will be set to 400 or greater and an error object will be returned, such as:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The Application row '37213410154d375de3e3620044382558' doesn't exist!"
   }
}

PHP Example:

This example prints information about a particular case:

$caseId = "36722263554ca70b82c52e8020802754";
$oRet = pmRestRequest("GET", '/api/1.0/workflow/cases/' . $caseId);
if ($oRet == 200 and !empty($oRet->response)) {
   print "Case {$oRet->response->app_name} was started by {$oRet->response->app_init_usr_username} " .
      "on {$oRet->response->app_create_date} and was last updated on {$oRet->response->app_update_date}\n";
   foreach ($oRet->response->current_task as $oTask) {
      print "Task {$oTask->tas_title} is assigned to {$oTask->usr_name}.\n";
   }
}

Get Case's Current Tasks: GET /cases/{app_uid}/current-task

Get the current task(s) of a case. Take into account the following:

  • If this endpoint is called for a case that has already been completed, then there is no current task and an error returns.
  • This endpoint does not verify permissions including PM_ALLCASES, it just verifies if the user belongs to the used token and has participated in the case. Then, to work correctly with this endpoint, the logged on user must be currently assigned to work on the case.

GET /api/1.0/{workspace}/cases/{app_uid}/current-task

URL Parameters:

Parameter Description Example
workspace Workspace name which by default is "workflow". /api/1.0/workflow/cases/37213410154d375de3e3620044382558/current-task
app_uid Case's unique ID. /api/1.0/workflow/cases/37213410154d375de3e3620044382558/current-task

Result:

If successful, then sets the HTTP status code to 200 and returns an array of task objects, such as:

[
   {
      "tas_uid":   "53643749052af5bdef3ca79050192707",
      "tas_title": "Advise Loan Officer",
      "del_index": "2"
   },
   {
      "tas_uid":   "740892399532b1da90901a9001372427",
      "tas_title": "Credit Check",
      "del_index": "3"
   }
]

Otherwise, the HTTP status code is set to 400 or greater and a error is returned, such as:

{
  "error": {
     "code":    400,
     "message": "Bad Request: Incorrect or unavailable information about this case: 37213410154d375de3e3620044382558"
   }
}

Note: If a case has "COMPLETED", "PAUSED", "CANCELLED" or "DELETED" status, then the above error object is returned.

PHP Example:

$caseId = "36722263554ca70b82c52e8020802754";
$oRet = pmRestRequest("GET", "/api/1.0/workflow/cases/$caseId/current-task");
if ($oRet == 200 and !empty($oRet->response)) {
   print "Current Tasks:\n";
   foreach ($oRet->response as $oTask) {
      print "Task {$oTask->tas_title}.\n";
   }
}

Get Case's Tasks: GET /cases/{app_uid}/tasks

Get all the tasks of a case, including completed, current and future tasks.

GET /api/1.0/{workspace}/cases/{app_uid}/tasks

Method: workflow/engine/src/ProcessMaker/Services/Api/Cases.php: doGetTasks($app_uid)

Note: This endpoint will not indicate whether a case has been canceled, paused or completed. The task's status property it returns can be deceptive, since it lists "TASK_COMPLETED" when all the steps are completed but before routing to the next task. If needing to know the overall status of a case or to be sure which is the current task, is recommended to call another endpoint such as GET api/1.0/{workspace}/cases/{app_uid} and check its app_status and current_task.

URL Parameters:

Parameter Description Example
workspace Workspace name which by default is "workflow". /api/1.0/workflow/cases/37213410154d375de3e3620044382558/tasks
app_uid Case's unique ID. /api/1.0/workflow/cases/37213410154d375de3e3620044382558/tasks

Result:

If successful, then sets the HTTP status code to 200 and returns an array of task objects:

[ Start array of task objects
{ Start task object
"tas_uid": Unique ID of the task
"tas_title": Title of the task
"tas_description": Description of the task
"tas_start": Set to 1 if the task has already been opened to start working on it. If not yet opened, then set to 0
"tas_type": Type of task, which can be: "NORMAL", "ADHOC" (if task can be reassigned to an ad hoc user) or "SUBPROCESS"
"tas_derivation": Type of derivation which is always "NORMAL"
"tas_assign_type": Task's assignment rule, which can be:
"BALANCED" (cyclical assignment)
"MANUAL" (Manual assignment)
"EVALUATE" (Value Based Assignment)
"REPORT_TO" (Reports to)
"SELF_SERVICE" (Self Service)
"SELF_SERVICE_EVALUATE" (Self Service Value Based Assignment)
"usr_uid": Unique ID of user assigned to work on the task
"usr_username": Username of user assigned to work on the task
"usr_firstname": First name of user assigned to work on the task
"usr_lastname": Last name of user assigned to work on the task
"element_uid":

Available Version: As of ProcessMaker 3.3.0

If the task is a dummy, it returns the EVN_UID. Otherwise it returns the corresponding tas_uid
"route": Object with information about next task to route to in the process
{
"type": Type of routing, which can be: "SEQUENTIAL", "SELECT", "EVALUATE", "PARALLEL", "PARALLEL-BY-EVALUATION", "SEC-JOIN" or "DISCRIMINATOR"
"to": An array of routes. If "type" is not "PARALLEL", then only one route
[
{
"rou_number": Route number. The first route is 1, the second route is 2, etc
"rou_condition": If the route has a condition which needs to evaluate to true to execute the route, then the text of the route, such as "@@FIELD1 == 3"
"tas_uid": The unique ID of the next task in the process
},
... Any additional routes if type is "PARALLEL" or "PARALLEL-BY-EVALUATION"
]
},
"delegations": An array which has one delegation object which holds information about the routing. For future tasks (i.e., status is set to "TASK_PENDING_NOT_EXECUTED"), this will be an empty array
[
{
"del_index": The delegation index number, which starts counting from 1. Each time a case is routed to any task, the delegation index is incremented, so the first task is 1, the second is 2, etc
"del_init_date": The datetime in YYYY-MM-DD HH:MM:SS format when the task is first opened to work on it. If never opened, then set to "Case not started yet"
"del_task_due_date":The datetime in YYYY-MM-DD HH:MM:SS format when the task is due to be finished, calculated from the time when routed and the expected time to complete it, taking into account its calendar
"del_finish_date": The datetime in YYYY-MM-DD HH:MM:SS format when the task was completed. If not yet completed, then set to "Not finished"
"del_duration": The time it took to complete the task in X Hours X Minutes X Seconds format. If not yet completed, then set to "Not finished"
"usr_uid": The unique ID of the user assigned to work on the task
"usr_username": The username of the user assigned to task
"usr_firstname": The first name of the user assigned to the task
"usr_lastname": The last name of the user assigned to the task
}
],
"status": The task's status, which can be:
"TASK_IN_PROGRESS" (a current task in the case, which is not yet completed)
"TASK_COMPLETED" (a task which has finished all of its steps, but the user may still have to click on the Continue button to route to the next task in the process),
"TASK_PENDING_NOT_EXECUTED" (a future task in the process)
"TASK_PARALLEL" (multiple tasks executed in parallel between a split and a join)
},
... Any additional tasks.
]

For example:

[
   {
      "tas_uid":         "64109086255b6822b4aaa00042124344",
      "tas_title":       "Register Client",
      "tas_description": "Task to register a new client",
      "tas_start":       1,
      "tas_type":        "NORMAL",
      "tas_derivation":  "NORMAL",
      "tas_assign_type": "BALANCED",
      "usr_uid":         "24175319155b67db9cb2b77069631302",
      "usr_username":    "wendy",
      "usr_firstname":   "Wendy",
      "usr_lastname":    "Smith",
      "element_uid": "64109086255b6822b4aaa00042124344",
      "route":
      {
         "type":         "PARALLEL",
         "to":
         [
            {
               "rou_number":    1,
               "rou_condition": "",
               "tas_uid":       "71294923755b67a04a06590067310340",
            },
            {
               "rou_number":    2,
               "rou_condition": "",
               "tas_uid":       "81106116155b679c396cd47013780044",
            }
         ]
      },
      "delegations":
      [
         {
            "del_index":         1,
            "del_init_date":     "2015-07-27 15:15:39",
            "del_task_due_date": "2015-07-28 15:15:39",
            "del_finish_date":   "2015-07-27 15:16:16",
            "del_duration":      "0 Hours 0 Minutes 37 Seconds",
            "usr_uid":           "24175319155b67db9cb2b77069631302",
            "usr_username":      "wendy",
            "usr_firstname":     "Wendy",
            "usr_lastname":      "Smith",
         }
      ],
      "status":          "TASK_COMPLETED"
   },
   {
      "tas_uid":         "71294923755b67a04a06590067310340",
      "tas_title":       "Check Financial Records",
      "tas_description": "Verify credit history and credit limits",
      "tas_start":       0,
      "tas_type":        "NORMAL",
      "tas_derivation":  "NORMAL",
      "tas_assign_type": "BALANCED"
      "usr_uid":         "28764296455b67dddd0b292072145342",
      "usr_username":    "silvia",
      "usr_firstname":   "Silvia",
      "usr_lastname":    "Pajoli",
      "element_uid": "71294923755b67a04a06590067310340",
      "route":
      {
         "type":   "SEC-JOIN",
         "to":
         [
            {
               "rou_number":    1,
               "rou_condition": "",
               "tas_uid":       -1
            }
         ],
      },
      "delegations":
      [
         {
            "del_index":         3,
            "del_init_date":     "Case not started yet",
            "del_task_due_date": "2015-07-28 15:16:41",
            "del_finish_date":   "Not finished",
            "del_duration":      "Not finished",
            "usr_uid":           "28764296455b67dddd0b292072145342",
            "usr_username":      "silvia",
            "usr_firstname":     "Silvia",
            "usr_lastname":      "Pajoli"
         }
      ],
      "status":    "TASK_IN_PROGRESS"
   },
   {
        "tas_uid": "icte-25865963885e8aba81022732901",
        "tas_title": "INTERMEDIATE-CATCH-TIMER-EVENT",
        "tas_description": "",
        "tas_start": 0,
        "tas_type": "INTERMEDIATE-CATCH-TIMER-EVENT",
        "tas_derivation": "NORMAL",
        "tas_assign_type": "BALANCED",
        "usr_uid": "",
        "usr_username": "",
        "usr_firstname": "",
        "usr_lastname": "",
        "element_uid": "62245879259638859b55592054170245",
        "route": {
            "type": "SEQUENTIAL",
            "to": [
                {
                    "rou_number": 1,
                    "rou_condition": "",
                    "tas_uid": "434299217596387e1330779028176296"
                }
            ]
        },
        "delegations": [],
        "status": "TASK_PENDING_NOT_EXECUTED"
    }
]

Otherwise, the HTTP status code is set to 400 or greater and a error is returned, such as:

{
  "error": {
     "code":    400,
     "message": "Bad Request: Incorrect or unavailable information about this case: 37213410154d375de3e3620044382558"
   }
}

PHP Example:

$caseId = "36722263554ca70b82c52e8020802754";
$oRet = pmRestRequest("GET", "/api/1.0/workflow/cases/$caseId/tasks");
if ($oRet == 200 and !empty($oRet->response)) {
   print "Tasks in case:\n";
   foreach ($oRet->response as $oTask) {
      print "Task {$oTask->tas_title} status: {$oTask->status}.\n";
   }
}

Get Starting Tasks: GET /case/start-cases

Get a list of the starting tasks to which the logged on user is assigned. This endpoint can be called to discover to the processes and tasks where the logged on user can start cases. Then, call POST /cases to start the new case.

GET /api/1.0/{workspace}/case/start-cases

URL Parameters:

Parameter Description Example
{workspace} Workspace name. https://example.com/api/1.0/workflow/cases

Result:

If successful, then the HTTP status code is set to 200 and the following object is returned:

Example element Description
[ Start array of objects.
{ Start object with information about starting task & process.
"tas_uid": "758892601578418e53c3000032096252", Unique ID of the starting task.
"pro_title": "Leave Request (Petition for Leave)", Title of the process, with the title of the starting task in parentheses.
"pro_uid": "9509036465784173c9f2c38084957729" Unique ID of the process.
}, End task.
... Any additional objects.
] End array.

Example:

Response:

200 (OK)
[
  {
    "tas_uid":   "758892601578418e53c3000032096252",
    "pro_title": "Leave Request (Petition for Leave)",
    "pro_uid":   "9509036465784173c9f2c38084957729"
  },
  {
    "tas_uid":   "3609934335775a15491fb93026385324",
    "pro_title": "Audit Expenses (Collect Data)",
    "pro_uid":   "5102810345775a127c4b089064023755"
  },
  {
    "tas_uid":   "37439823957314102c66d78026868117",
    "pro_title": "New employee onboarding (Safety Training)",
    "pro_uid":   "798659366573140bc117490080056441"
  }
]

Get Sub-Process Cases: GET /cases/{app_uid}/sub-process-cases

Available Version: As of ProcessMaker 3.3.4.

Get a cases list of a sub-process. Take into account the endpoint doesn't display information for a sub-process' cases for another sub-process.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

GET /api/1.0/{workspace}/cases/{app_uid}/sub-process-cases

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/51382566154f7180953b5e1028461947/sub-process-cases
{app_uid} The unique ID of the parent case to obtain the children cases in the sub-process. /api/1.0/workflow/cases/51382566154f7180953b5e1028461947/sub-process-cases

Result:

If successful, then the HTTP status code is set to 200 and the response is an array of all sub-process children cases of the parent case provided in the parameters. Each item in the array is a sub-process case that shows the same case information as the same data is returned in the endpoint GET /cases/{app_uid}. For example:

200(OK)
Content-Type: application/json
{
    "app_uid": "6706682895a29a71612d965010391969",
    "app_number": 1098,
    "app_name": "#1098",
    "app_status": "TO_DO",
    "app_init_usr_uid": "95198418458763f3e5cf263045961212",
    "app_init_usr_username": "John Doe",
    "pro_uid": "257072085595f8b3a132b64086222304",
    "pro_name": "[P SubProcess",
    "app_create_date": "2017-12-07 20:39:50",
    "app_update_date": "2017-12-07 20:39:51",
    "current_task":
    [
        {
            "delStatus": "TO_DO",
            "delInitDate": null,
            "delTaskDueDate": "2017-12-08 20:39:50",
            "usr_uid": "95198418458763f3e5cf263045961212",
            "usr_name": "John Doe",
            "tas_uid": "570530924595f8b601e41e4062567245",
            "tas_title": "Ciclical",
            "del_index": "1",
            "del_thread": "1",
            "del_thread_status": "OPEN",
            "del_init_date": "",
            "del_task_due_date": "2017-12-08 20:39:50"
        }
    ]
}
   

If an error occurs, then the HTTP status code sets to 400 or greater and an error object returns:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The Application row '37213410154d375de3e3620044382558' doesn't exist!"
   }
}

New Case: POST /cases

Start a new case and assign the logged on user to work on the initial task in the case. Note that the logged on user must be in the pool of assigned users for the initial task. Also note that the new case's status will be set to "DRAFT", not "TO_DO". If wishing to change the new case's status to "TO_DO", then create the following trigger in the process and use PUT /cases/{app_uid}/execute-trigger/{tri_uid} to execute it.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

POST /api/1.0/{workspace}/cases

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases

POST Parameters:

Parameter Type Description Example
pro_uid String Unique ID of process/project. "11703471254f718165880f2035616306"
tas_uid String Unique ID of the initial task to start the case. This should be a task with a start event. "33432552454f5c38aa3a620081949840"
variables Array Optional. An object of case variables inside an array that will be set in the new case. These variables can be used in Dynaform fields, triggers and the templates for email notifications and Output Documents. See Format of Variables below. It is recommended to send the _label variable. To display fields correctly, it is mandatory to send the _label variable when using Checkgroup, Dropdown, Radio and Suggest in a Grid.
[{
  "client": "Acme Inc.",
  "amount": 23456.99,
  "dateDue": "2015-12-31 23:59:59",
  "contractCheckbox": ["1"],
  "contactCheckgroup": ["fax","email","phone"],
  "gridVar001": {
1:{
"text02":"test textbox 1",
"text02_label":"test textbox 1",
"textarea02":"test textarea 1",
"textarea02_label":"test textarea 1",
"dropdown02":"NY",
"dropdown02_label":"New York",
"checkbox02":1,
"checkbox02_label":true,
"datetime02": "2020-11-10",
"datetime02_label": "2020-11-10",
"suggest01":"NY",
"suggest01_label":"New York",
"hidden02":"test hidden 1",
"hidden02_label":"test hidden 1"
}
}]

Result:

If a new case was created, then the HTTP status code is set to 200 and the following object is returned:

{
   "app_uid":    "72820966053275dc14650d6041630056",
   "app_number": 49
}

If an error occurred, then the HTTP status code is set to 400 or greater and an error object, such as the following is returned:

{
   "error": {
      "code":    400,
      "message": "Bad Request: `tas_uid` is required but missing."
   }
}

Format of Variables

The case variables to be set in the new case passed are placed in a object, which is enclosed in an array in this format:

Note: It is recommended to send the _label variable. To display fields correctly, it is mandatory send the _label variable when using Checkgroup, Dropdown, Radio and Suggest in a Grid.

[ { "variable1": "value1", "variable1_label": "value1", "variable2": "value2", "variable2_label": "value2", ... } ]

The variable names in the object are case sensitive and must start with a letter or underscore. Numbers may be used in variable names as long as they are not the first letter, but spaces and symbols are not allowed. Variable names may contain international letters with a value of less than 256 are allowed, but they aren't recommended, because they can cause character set translation problems.

ProcessMaker will save the variables to a MySQL database which uses the UTF-8 character set, so strings which are in other character sets need to be converted to UTF-8. mb_convert_encoding() in PHP or iconv-lite in JavaScript can be used to convert to UTF-8.

Boolean values of true and false will automatically be converted to "1" and "0" when passed to ProcessMaker, and all numbers will automatically be converted to strings. If the value is a floating point number (i.e., real number with decimal), remember to NOT use a thousands separator and to use a dot for the decimal point.

If setting the value of a dropdown box or radiogroup, remember to set the variable to the value, and not its label. The value(s) of checkboxes and checkbox groups are enclosed inside an array, but when a field inside a grid, the values of checkboxes are enclosed inside an array. If a checkbox is based on boolean variable, then use ["0"] (unmarked) or ["1"] (marked). If a checkbox is based on a string variable, then use [""] to unmark it or ["value"] to mark it. For a checkbox group (i.e., multiple checkboxes), use an array of the values of the marked options: ["value1", "value2", ...]

To set the value of a datetime field, use "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS" format, such as "2015-12-31 23:59:59"

Most types of DynaForm input fields have an associated variable and a corresponding variable_label. For textboxes and textareas, the variable_label holds the same value as the variable. For dropdown boxes and radiogroups, the variable_label holds the label of the selected option. For checkboxes and checkbox groups, variable_label holds a JSON string of the labels of the selected option(s): '["label1", "label2", ...]'
For datetimes, variable_label holds the formatted datetime according to its Format property.

DynaForm fields only use the variable and ignore the variable_label when setting their values, so it isn't necessary to set the variable_label for DynaForms, although if may be necessary if using variable_label in triggers, Output Document templates or email notification templates.

To set the contents of a grid, use an object of row objects. Each row in the grid is numbered starting from 1 and each row object contains properties which are the IDs of the fields in the grid: { "1": {"field1-id": "value1", "field2-id": "value2", ...}, "2": {"field1-id": "value1", "field2-id": "value2", ...}, ... } If using PHP, it is also possible to use an associative array of associative arrays, which is how ProcessMaker stores grids. The rows are numbered starting from 1 and the IDs of the fields in the grid are the keys in the inner associative arrays: array( "1" => array("field1-id" => "value1", "field2-id" => "value2", ...), "2" => array("field1-id" => "value1", "field2-id" => "value2", ...), ... )

If using PHP, associative arrays will automatically be converted to objects when passed to a REST endpoint since JSON doesn't support associative arrays, but ProcessMaker can read either objects or associative arrays when loading values in a DynaForm grid. The only problem is if using trigger code to access a grid which is stored in ProcessMaker as an object rather than an associative array, because this will NOT work:

$var = @=mygrid->1->myfield;
It is not possible to access an object's property whose name is a number. The solution is to use the get_object_vars() function to convert the object into an associative array:
if (is_object(@=mygrid)) {
  $grd = array();
  foreach(@=mygrid as $rowNo => $oRow) {
     $grd[$rowNo] = get_object_vars($oRow);
  }
  @=mygrid = $grd;
}
$var = @=mygrid[1]["myfield"];

PHP Example:

To create a new case without setting new variables in the case:

$aVars = array(
   'pro_uid'   => '325089587550b34ab5471f8086074839',
   'tas_uid'   => '491406639550b34b27f0b34088369199'
);
$oRet = pmRestRequest('POST', '/api/1.0/workflow/cases', $aVars);

if ($oRet->status == 200) {
   print "New Case {$oRet->response->app_number} created.\n";
}

This example shows how to create a new case which contains different types of fields and different types of variables. Note that the variables are placed inside an associative array, which is inside an array. The grid is a numbered array of associative arrays.

$aCaseVars = array(array(
   "client"            => 'Acme Inc.',                        //textbox with string variable
   "amount"            => 23456.99,                           //textbox with float variable
   "address"           => "245 Stars Av.\nHollywood CA 12345",//textarea with string variable
   "dateDue"           => '2015-12-31',                       //datetime
   "dateDue_label"     => '12/31/2015',                       //datetime label in MM/DD/YYYY format
   "deliveryTime"      => '2015-11-25 17:55:38',              //datetime
   "serviceType"       => 'accounting',                       //dropdown with string variable
   "serviceType_label" => 'Accounting Review',                //dropdown label
   "hasContract"       => array('1'),                         //checkbox with boolean variable
   "hasContract_label" => 'yes',                              //checkbox label
   "howContact"        => array('fax', 'email', 'telephone'), //checkbox group with string variable
   "howContact_label"  => '["Fax","Send Email","Telephone"]', //checkbox group label in JSON string
   "contactsGrid"      => array(
      '1' => array('fullName' => 'Jane Doe',   'canCall' => '1', 'canCall_label' => 'Yes'),
      '2' => array('fullName' => 'Bill Hill',  'canCall' => '0', 'canCall_label' => 'No'),
      '3' => array('fullName' => 'Sally Slim', 'canCall' => '1', 'canCall_label' => 'Yes')
   )
));
$aVars = array(
   'pro_uid'   => '325089587550b34ab5471f8086074839',
   'tas_uid'   => '491406639550b34b27f0b34088369199',
   'variables' => $aCaseVars
);

$oRet = pmRestRequest('POST', '/api/1.0/workflow/cases', $aVars);

if ($oRet->status == 200) {
   print "New Case {$oRet->response->app_number} created.\n";
}

JavaScript Example:

var oVars = {
   'pro_uid'  : '325089587550b34ab5471f8086074839',
   'tas_uid'  : '491406639550b34b27f0b34088369199',
   'variables': [{
      "client":            'Acme Inc.',                        //textbox with string variable
      "amount":            23456.99,                           //textbox with float variable
      "address":           '245 Stars Av.\nHollywood CA 12345',//textarea with string variable
      "dateDue"            '2015-12-31',                       //datetime
      "dateDue_label"      '12/31/2015',                       //datetime label in MM/DD/YYYY format
      "deliveryTime":      '2015-11-25 17:55:38',              //datetime
      "serviceType":       'accounting',                       //dropdown with string variable
      "serviceType_label": 'Accounting Review',                //dropdown label
      "hasContract":       ['1'],                              //checkbox with boolean variable
      "hasContract_label": 'yes',                              //checkbox label
      "howContact":        ['fax', 'email', 'telephone'],      //checkbox group with string variable
      "howContact_label":  '["Fax","Send Email","Telephone"]', //checkbox group label in JSON string
      "contactsGrid":      {
         '1': {'fullName': 'Jane Doe',   'canCall': '1', 'canCall_label': 'Yes'},
         '2': {'fullName': 'Bill Hill',  'canCall': '0', 'canCall_label': 'No'},
         '3': {'fullName': 'Sally Slim', 'canCall': '1', 'canCall_label': 'Yes'}
      }
   }]
};

pmRestRequest("POST","/api/1.0/workflow/cases", oVars, false);

if (httpStatus == 200 && oResponse) {
   alert("Case " + oResponse->app_number + " created.");
}

New Case Impersonate: POST /cases/impersonate

Creates a new case. It is similar to POST /cases, but it allows cases to be created which are assigned to other users. It also impersonates the session variables, so it is more robust than POST /cases. Note that the specified user to work on the case must be assigned to the pool of users for the initial task. Also note that the new case's status will be set to "DRAFT", not "TO_DO". If wishing to change the new case's status to "TO_DO", then create the following trigger in the process and use PUT /cases/{app_uid}/execute-trigger/{tri_uid} to execute it.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

POST /api/1.0/{workspace}/cases/impersonate

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/impersonate

POST Parameters:

Parameter Type Description Example
pro_uid String Unique ID of process/project. "11703471254f718165880f2035616306"
usr_uid String Unique ID of user who will be assigned to initial task in case. "51382566154f7180953b5e1028461947"
tas_uid String Unique ID of the initial task to start the case. This should be a task with a start event. "33432552454f5c38aa3a620081949840"
variables Array Optional. Variables that are set in the new case. See New Case: POST /cases for more information. It is recommended to send the _label variable. To display fields correctly, it is mandatory send the _label variable when using Checkgroup, Dropdown, Radio and Suggest in a Grid.
[{"client": "Acme Inc.", "client_label": "Acme Inc.", "amount": 23456.99}, "amount_label": 23456.99},"gridVar001": {
1:{
    "text02":"test textbox 1",
    "text02_label":"test textbox 1",
    "textarea02":"test textarea 1",
    "textarea02_label":"test textarea 1",
    "dropdown02":"NY",
    "dropdown02_label":"New York",
    "checkbox02":1,
    "checkbox02_label":true,
    "datetime02": "2020-11-10",
    "datetime02_label": "2020-11-10",
    "suggest01":"NY",
    "suggest01_label":"New York",
    "hidden02":"test hidden 1",
    "hidden02_label":"test hidden 1"
}]


Result:

If a new case was created, then the HTTP status code is set to 200 and the following object is returned:

{
   "app_uid":    "72820966053275dc14650d6041630056",
   "app_number": 49
}

If an error occurred, then the HTTP status code is set to 400 or greater and an error object, such as the following is returned:

{
   "error": {
      "code":    400,
      "message": "`usr_uid` is required but missing."
   }
}

PHP Example:

$aVars = array(
   'pro_uid'   => '605620179552bf966f19e04097908938',
   'tas_uid'   => '444632093552bf96dd52ad3017304502',
   'usr_uid'   => '548701171552bfeb017dc68013956351'
);

$url = "/api/1.0/workflow/cases/impersonate";
$method = "POST";
$oRet = pmRestRequest($method, $url, $aVars);
if ($oRet->status == 200) {
   print "New Case {$oRet->response->app_number} created.\n";
}

Reassign Case: PUT /cases/{app_uid}/reassign-case

Reassign a case to a different user.

Permission:

Users must have the PM_REASSIGNCASE or PM_REASSIGNCASE_SUPERVISOR permission assigned to their role to perform this action.

Structure:

PUT /api/1.0/{workspace}/cases/{app_uid}/reassign-case

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/reassign-case
app_uid Case's unique ID. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/reassign-case

PUT Parameters:

Parameter Type Description Example
usr_uid_source String Required. Unique ID of user currently assigned to case. "41089101154de3b97536fc0077548396"
usr_uid_target String Required. Unique ID of user to be assigned to case. Make sure that this user is in the pool of assigned users or ad hoc users for the case's current task. "98883020754dd1f052ee1f1034403381"
del_index integer Optional. The delegation index of the task which will be reassigned. If not specified, then automatically set to the most recent open task in the case. Only needs to be specified if there are multiple open tasks in the case. 5

Result:

If successful, then the HTTP status code will be set to 200 and there will be no return value. If unsuccessful, then the HTTP status code will be 400 or higher and an error object will be returned.

Example:

Request

 Content-Type: application/json
 {
  "usr_uid_source": "23063198853206b666e2bd0085065170",
  "usr_uid_target": "00000000000000000000000000000001"
 }

Response

 200(OK)

Batch Reassigning Cases: POST /cases/reassign

Reassign multiple cases to a specified user.

Remember that paused cases can't be reassigned and a case can't be reassigned to the same user that is currently assigned.

Permission:

Users needs to be Supervisor of the processes to which the cases belong to or needs to have the PM_REASSIGNCASE permission assigned to their role to perform this action.

Structure:

POST /api/1.0/{workspace}/cases/reassign

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/reassign

POST Parameters:

Parameter Type Description Example
APP_UID String Required. Unique ID of the case. "775512695580a23a40d7bb6035424645"
DEL_INDEX Integer Required. The delegation index of a current task which will be reassigned. The delegation index counts a case starting from 1. The first task in a process has a delegation index of 1, the second task is 2, etc. 3
usr_uid_target String Required. Unique ID of user to be assigned to case. Make sure that this user is in the pool of assigned users or ad hoc users for the case's current task. "98883020754dd1f052ee1f1034403381"

Example:

Request

 Content-Type: application/json
{
    "cases": [
        {
            "APP_UID":"775512695580a23a40d7bb6035424645",
            "DEL_INDEX":2
        },
        {
            "APP_UID":"175994873580a23f3da1670048245491",
            "DEL_INDEX":2
        }
    ],
    "usr_uid_target": "418853759580927a093f456004300548"
}

Response

If successful, then the HTTP status code is set to 200 and there is a return object:

 200(OK)
"{
    \"cases\":
    {
        \"0\":
        {
            \"APP_UID\":\"775512695580a23a40d7bb6035424645\",
            \"DEL_INDEX\":2
        },
        \"1\":
        {
            \"APP_UID\":\"175994873580a23f3da1670048245491\",
            \"DEL_INDEX\":2
        },
        \"USR_UID\":
        {
            \"result\":1,
            \"status\":\"SUCCESS\"
        }
    }
}"

Notice that the endpoint response is individual for each case. If a case reassignment fails, the reassignment of other cases won't be interrupted.

Examples:

If the delegation index or the case UID of one of the cases doesn't exist, then the HTTP status code is set to 200 and an error object is returned, such as:

{
    "cases": [
    {
        "app_uid": "175994873580a23f3da1670048245491",
        "del_index": 2,
        "result": 0,
        "status": "DELEGATION_NOT_EXISTS"
    }
    ]
}

If the user is not included in the assignment pool, the following error object is returned:

{
    "cases": [
    {
        "app_uid": "775512695580a23a40d7bb6035424645",
        "del_index": 2,
        "result": 0,
        "status": "USER_NOT_ASSIGNED_TO_TASK"
    },
    {
        "app_uid": "175994873580a23f3da1670048245491",
        "del_index": 2,
        "result": 0,
        "status": "USER_NOT_ASSIGNED_TO_TASK"
    }
    ]
}

Route Case: PUT /cases/{app_uid}/route-case

Route a case (i.e., move the case to the next task in the process according to the routing rules). Cases may only be routed if the logged on user is the case's currently assigned user. If needing to route a case which is assigned to another user, then first reassign the case to the logged on user and then route the case. Note that "routing" is also known as "derivating" in ProcessMaker.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

PUT /api/1.0/{workspace}/cases/{app_uid}/route-case

Method: workflow/engine/src/ProcessMaker/Services/Api/Cases.php: doPutRouteCase($app_uid, $del_index = null)

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/route-case
app_uid Case's unique ID. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/route-case

PUT Parameters:

Parameter Description
del_index Optional. Specify the delegation index of a current task which will be routed. The delegation index counts the routings for a case starting from 1. The first task in a process has a delegation index of 1, the second task is 2, etc. If this parameter is not included, then the current task with the highest delegation index will be routed.
executeTriggersBeforeAssignment Optional. By default, it is set as false. If set to true, any triggers before assignment will be executed. It is not recommended to set the value to true, because then the API will generate an infinite loop.

Result:

If successful, then the HTTP status code is set to 200 and there is no return object. If an error occurred, then the HTTP status code is set to 400 or greater and an error object is returned, such as:

{
  "error": {
    "code": 400,
    "message: "Bad Request: This case delegation is already closed or does not exist"
  }
}

PHP example:

In this example, there are 3 parallel current tasks, so the delegation index 5 will be specified to route the case:

$method = "PUT";
$caseId = '19862001855b935d6eeafc6001433267';
$aParams = array(
   "del_index" => 5
);
$oRet = pmRestRequest($method, $url, $aParams);
if ($oRet and $oRet->status == 200) {
   print "Case routed.\n";
}

Cancel Case: PUT /cases/{app_uid}/cancel

Allows a logged in user to cancel an assigned case that is in "TO DO" status. The case's status is changed to "CANCELLED" and it is no longer possible to open or change the case, but all the data for the case remains in the database. As of ProcessMaker 3.3.0, if there are parallel threads, the delegation index of the current task in the case needs to be opened in one thread.

Permission:

Users must have the PM_CANCELCASE permission assigned to their role to perform this action.
Users must have the permission over the case permission (Current user or Supervisor over the process).

Structure:

PUT /api/1.0/{workspace}/cases/{app_uid}/cancel

Warning: The Cancel Case mobile lightendpoint is not implemented yet.

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/cancel
app_uid Case's unique ID. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/cancel

Result:

If successful, the HTTP status code is set to 200 and there is no return value. If an error occurred, then the HTTP status code is set to 300 or greater, and an error object is returned, such as:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The case '54645427555b94ac7c633d4062829308' is already canceled"
   }
}

PHP example:

$caseId = '54645427555b94ac7c633d4062829308';
$url = "/api/1.0/workflow/cases/$caseId/cancel";
$oRet = pmRestRequest("PUT", $url);
if ($oRet and $oRet->status == 200) {
   print "Case $caseId canceled.\n";
}

Pause Case: PUT /cases/{app_uid}/pause

Pause a case.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

PUT /api/1.0/{workspace}/cases/{app_uid}/pause
which allows any user to change the variables on any case. This endpoint also

Warning: To pause a case, the logged on user should either be currently assigned to work on the case or should have access to the case as a Process Supervisor.

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/pause
app_uid Case's unique ID. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/pause

PUT Parameters:

Parameter Description Example
unpaused_date Date in "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS" format when the case will be unpaused. If the case will be paused indefinitely, then set this parameter as "" (empty string). "2015-05-21 23:59:59"

Result:

If successful, then the HTTP status code will be set to 200 and there will be no return value. If an error occurred, then the HTTP status code will be 300 or greater and an error object will be returned, such as:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The application with $app_uid: '55519601555ba4b4bd5a3c9097861253' does not exist."
   }
}

PHP example:

$aVars = array(
   "unpaused_date" => "2016-12-31"
);
$caseId = '55519601555ba4b4bd5a3c9097861253';
$url = "/api/1.0/workflow/cases/$caseId/pause";
$method = "PUT";
$oRet = pmRestRequest($method, $url, $aVars);
if ($oRet->status == 200) {
   print "Case $caseId paused.\n";
}

Unpause Case: PUT /cases/{app_uid}/unpause

Unpause a case which was previously paused. After being unpaused, the case may be opened and worked on again.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

PUT /api/1.0/{workspace}/cases/{app_uid}/unpause

Warning: In order to unpause a case, the logged on user should either be currently assigned to work on the case or should have access to the case as a Process Supervisor.

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/unpause
app_uid Case's unique ID. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/unpause


PUT Parameters:

Parameter Description Example
unpaused_date Optional. The date in "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS" format when the cases will be unpaused. If not included or set to "" (empty string), then the case will be immediately unpaused. "2015-12-31"

Result:

If successful, then the HTTP status code is set to 200 and there is no return object. Otherwise, the HTTP status code is set to 300 or higher and an error object is returned, such as:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The application with $app_uid: '55519601555ba4b4bd5a3c9097861253' does not exist."
   }
}

PHP example:

$caseId = '55519601555ba4b4bd5a3c9097861253';
$url = "/api/1.0/workflow/cases/$caseId/unpause";
$method = "PUT";
$oRet = pmRestRequest($method, $url, $aVars);
if ($oRet->status == 200) {
   print "Case $caseId unpaused.\n";
}

Execute Trigger: PUT /cases/{app_uid}/execute-trigger/{tri_uid}

Execute a trigger in a case.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

PUT /api/1.0/{workspace}/cases/{app_uid}/execute-trigger/{tri_uid}

URL Parameters:

Parameter Description Example
workspace Workspace name. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674
app_uid Unique ID of the case where the trigger will be executed. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674
tri_uid Unique ID of the trigger to execute. To find a trigger's UID, search in the wf_{workspace}.TRIGGERS.TRI_UID field in the database. Note that the trigger can be executed, even if it is not assigned to fire in the case's process. /api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674

Result:

If successful, then the HTTP status code is set to 200 and there is no return object. If an error occurred, then the HTTP status code is set to 400 or greater and an error object is returned, such as:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The application with $app_uid: '55519601555ba4b4bd5a3c9097861253' does not exist."
   }
}

PHP Example:

A trigger with the ID "37823572555ba5891041136049273220" contains the code:

@@dueDate = date('Y-m-d', strtotime('+1 week'));
@@usersQuery = executeQuery("select * from USERS");
This trigger is executed and then the endpoint GET cases/{app_uid}/variables endpoint is executed to retrieve the @@dueDate and @@usersQuery variables which were set by the trigger.
$caseId = '55519601555ba4b4bd5a3c9097861254';
$triggerId = '37823572555ba5891041136049273220';
$url = "/api/1.0/workflow/cases/$caseId/execute-trigger/$triggerId";
$method = "PUT";
$oRet = pmRestRequest($method, $url);
if ($oRet->status == 200) {
   $url = "/api/1.0/workflow/cases/$caseId/variables";
   $varRet = pmRestRequest("GET", $url);

   if ($varRet == 200) {
      $dueDate = $varRet->response->dueDate;
      if (count($firstUser = $varRet->response->usersQuery) >= 1) {
         //convert to stdClass object to array:
         $aUsers = get_object_vars($varRet->response->usersQuery);
         $firstUser = $aUsers[1]->USR_USERNAME;
      }
   }
}

Note: The endpoint has a condition: only the user assigned to the case can execute the trigger. The putExecuteTriggerCase() method validates this condition from cases class.

Delete Case: DELETE /cases/{app_uid}

Delete a case, which means that its record is removed from the wf_<WORKSPACE>.APPLICATION table, so its case data is deleted. Other information may remain about the case in other database tables, such as APP_DELEGATION, APP_DOCUMENT, APP_MESSAGE, etc., plus any files uploaded or generated in the case will remain in the shared directory on the ProcessMaker server. Only cases in their initial task may be deleted by the currently assigned user to the case. For all other cases, it is recommended to cancel them using PUT /cases/{app_uid}/cancel.

Permission:

Users must have the PM_CASES permission assigned to their role to perform this action.

Structure:

DELETE /api/1.0/{workspace}/cases/{app_uid}/

URL Parameters:

Parameter Description Example
workspace Workspace name which by default is "workflow". /api/1.0/workflow/cases/37213410154d375de3e3620044382558
app_uid Case's unique ID. /api/1.0/workflow/cases/37213410154d375de3e3620044382558

Result:

If the case was deleted, the HTTP status code is set to 200 and there is no response. If an error occurs, the HTTP status code is 400 or greater and an error object is returned, such as:

{
   "error": {
      "code":    400,
      "message": "Bad Request: The application with $app_uid: '526107075552bffba498007040759388' does not exist."
   }
}

PHP Example:

$caseId = '526107075552bffba498007040759388';
$url = "/api/1.0/workflow/cases/$caseId";
$oRet = pmRestRequest("DELETE", $url);

if (!isset($oRet) or $oRet->status != 200) {
   print "Unable to delete case '$caseId'.\n";
}