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

Cases

The following endpoints are used to obtain information about cases and control the execution of cases:

Contents: [hide]

Filters for listing cases

The endpoints which return a list of cases, such as GET /cases, /cases/paged, /cases/draft, etc., will return by default up to 25 cases and sort the cases in descending order according to their case number, which means that cases created more recently will be listed first. Additional GET parameters can be included in the URL to change how many cases are returned, what database field is used to sort the cases and the sort order, plus include filters to only return cases from a specified process or process category or search for cases which contain a specified string.

URL Parameters:

Parameter Description Default value Example
start={number} The number of cases where the list begins. Consider the examples below.
  • If set to 0, then begin returns from the first case.
  • If set to 1, begin returns from the second case.
  • If set to 2, begin returns from the third case.
  • Etc.
 0 /api/1.0/workflow/cases?start=1&limit=10
limit={number} The maximum number of cases in the list. 25 /api/1.0/workflow/cases?start=11&limit=10
sort={field} The field in the wf_<WORKSPACE>.APP_CACHE_VIEW table by which the list of cases is sorted. The default is "APP_CACHE_VIEW.APP_NUMBER", which lists cases in the order they were created. APP_CACHE_VIEW.APP_NUMBER /api/1.0/workflow/cases?sort=APP_CACHE_VIEW.APP_UPDATE_DATE
dir={order} The order by which cases are listed which can be "ASC" (ascending) or "DESC" (descending). DESC /api/1.0/workflow/cases?dir=ASC
cat_uid={uid} The unique ID of a category. Only return cases whose process is in the specified category. To find the UIDs for categories in the wf_<WORKSPACE> database, use the following query:
SELECT CATEGORY_UID, CATEGORY_NAME FROM PROCESS_CATEGORY;		 /api/1.0/workflow/cases?cat_uid=11609821854ca4355344560009542371
pro_uid={uid} The unique ID of a process. Only return cases for the specified process. To find the UIDs for processes in the wf_<WORKSPACE> database, use the following query:
SELECT PRO_UID FROM PROCESS WHERE PRO_TITLE = 'Expense Report Process'		 /api/1.0/workflow/cases?pro_uid=28468941754ca473f9db401077958260
search={string} Case insensitive search for cases in the case's title and current task title. Make sure to URL encode the searched text in UTF-8, with a function like urlencode() in PHP or encodeURIComponent() in JavaScript, so that characters like " " (space) becomes %20 and "?" becomes %F3. /api/1.0/workflow/cases?search=Evaluate%20Costs

Calling /cases endpoints

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

If it returns a list of cases, then it will be an array of case objects. If it returns a page of cases, then access the array of cases objects located in its data member.

Case Object

The GET endpoints which return cases (such as /cases, /cases/paged, /cases/draft, etc.) enclose the information about each case in the following case object:

Element Description Example
{ Begin case object.
"app_uid": Unique ID of case. "50576446953235bfb797531078087088"
"del_index": Delegation index of case, which counts tasks executed in the case, starting from 1. "1"
"del_last_index": Last delegation index, which is the previous task in the case. "1"
"app_number": The Case Number, which counts cases in the workspace, starting from 1. "66"
"app_status": Current status of case: "TO_DO" (current task is assigned but not yet worked on), "DRAFT" (current task has been worked on, but not yet completed), "COMPLETED" (case terminated at an end event), "CANCELLED", "PAUSED", "DELETED" or "UNASSIGNED" (unclaimed self service cases) "TO_DO"
"usr_uid": Unique ID of user currently assigned to work on case. "00000000000000000000000000000001"
"previous_usr_uid": Unique ID of the previous user assigned to case. Set to empty string if the first task in the case and the current user is the first user assigned to the case. ""
"tas_uid": Unique ID of current task in case. "7983935495320c1a75e1df6068322280"
"pro_uid": Unique ID of the case's process. "2317283235320c1a36972b2028131767"
"del_delegate_date": Datetime in "YYYY-MM-DD HH:MM:SS" format when case was routed to the current task. "2014-03-14 15:43:55"
"del_init_date": Datetime in "YYYY-MM-DD HH:MM:SS" format when current task was initiated. If a self service task which hasn't yet been claimed by a user, then set to null. "2014-03-14 15:43:55"
"del_task_due_date": Datetime in "YYYY-MM-DD HH:MM:SS" format when the current task is due (scheduled to be completed). "2014-03-17 15:43:55"
"del_finish_date": Datetime in "YYYY-MM-DD HH:MM:SS" format when the current task was completed. Set to null if not yet completed. null
"del_thread_status": Status of the delegation thread which can be "OPEN" or "CLOSED", which indicates whether the current parallel task is still executing or has been completed or canceled. "OPEN"
"app_thread_status": Status of the case thread which can be "OPEN" or "CLOSED", which indicates whether the current task is still executing or has been completed or canceled. "OPEN"
"app_title": The case title, which by default is its case number, but can be customized by task properties. "#66"
"app_pro_title": The title for the case's process. "My process title"
"app_tas_title": The title of the current task in the case. "Task 1"
"app_current_user": The last name and first name (separated by space) of the user currently assigned to the case. " Administrator"
"app_del_previous_user": The last name and first name (separated by space) of the user assigned to the case's previous task. ""
"del_priority": The case's delegation priority which can be "VERY LOW" (1), "LOW" (2), "NORMAL" (3), "HIGH" (4) and "VERY HIGH" (5). "NORMAL"
"del_duration": No longer used and always set to "0". "0"
"del_queue_duration": No longer used and always set to "0". "0"
"del_delay_duration": No longer used and always set to "0". "0"
"del_started": "0", No longer used and always set to "0". "0"
"del_finished": "0", No longer used and always set to "0". "0"
"del_delayed": "0", No longer used and always set to "0". "0"
"app_create_date": Datetime in "YYYY-MM-DD HH:MM:SS" format when the case was first created. "2014-03-14 15:43:55"
"app_finish_date": Datetime in "YYYY-MM-DD HH:MM:SS" format when the case was completed or canceled. Set to null if not yet completed. null
"app_update_date": Datetime in "YYYY-MM-DD HH:MM:SS" format when the case was last updated, meaning data was changed, files were uploaded or the case was routed to another task. "2014-03-14 15:43:57"
"app_overdue_percentage": No longer used and always set to "0". "0"
"usr_firstname": First name of the user currently assigned to work on case. "Administrator"
"usr_lastname": Last name of the user currently assigned to work on case. " "
"usr_username": Username of the user currently assigned to work on case. "admin"
"appcvcr_app_tas_title": Title of the current task in the case. "Task 1"
"usrcr_usr_uid": Unique ID of the user currently assigned to work on case. "00000000000000000000000000000001"
"usrcr_usr_firstname": First name of the user currently assigned to work on case. "Administrator"
"usrcr_usr_lastname": Last name of the user currently assigned to work on case. " "
"usrcr_usr_username": Username of the user currently assigned to work on case. "admin"
"app_status_label": The current case status, which can be "To do", "Draft", "Completed", "Cancelled", "Paused" or "Deleted". "To do"
} End case object.

Returning a list of cases

The GET endpoints which return a list of cases (such as /cases, /cases/draft, etc.) will return an array of case objects with the following structure:

[
  {   // first case object
    "app_uid": "50576446953235bfb797531078087088",
    ...
  },
  {   // second case object
    "app_uid": "33432552454f5c38aa3a620081949840",
    ...
  }
  ... // additional case objects
]

Reading a list of cases with JavaScript:

var req = new XMLHttpRequest();
req.open("GET", "https://example.com/api/1.0/workflow/cases", 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 aCases = (JSON) ? JSON.parse(req.responseText) : eval(req.responseText);

      //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 '" + aCases[i].app_title + "' in task '" + aCases[i].app_tas_title +
            "' is due " + aCases[i].del_task_due_date + ".";
         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);
$aCases = 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:
   foreach ($aCases as $oCase) {
      print "<p>Case '{$oCase->app_title}' in task '{$oCase->app_tas_title}' is due {$oCase->del_task_due_date}.</p>\n";
   }
}

Returning a page of cases

Each GET endpoint which returns a list of cases also has a corresponding endpoint which returns a page of cases, such as /cases/paged, /cases/draft/paged, /cases/participated/paged etc. A page is an object containing information about the total number of cases and the filters used to retrieve the cases. Its data member holds an array of case objects:

Element Description
{
"total": 6, Total number of cases found.
"start": 1, Number where the list of cases begins. The default is 1.
"limit": 25, Maximum number of cases returned. The default is 25.
"sort": "app_cache_view.app_number", The field in the wf_<WORKSPACE>.APP_CACHE_VIEW table which is used to sort the cases. The default is "app_cache_view.app_number".
"dir": "desc", The sort order of the cases, which can be "asc" (ascending) or "desc" (descending, which is the default).
"cat_uid": "", The unique ID of a process category. Only cases whose processes are in the given category will be returned.
"pro_uid": "", The unique ID of a process. Only cases in the given process will be returned.
"search": "", A case insensitive string to search for in the case title and task title.
"data": An array of case objects.
 [
   { //first case object
     "app_uid": "50576446953235bfb797531078087088",
     ...
   },
   { //second case object
     "app_uid": "33432552454f5c38aa3a620081949840",
     ...
   }
 ]
} End of the page object.

It is recommended to use the endpoints which return a page of cases when needing to know the total number of cases which are available. If needing to retrieve all the available cases at once, first call the GET /cases.../paged endpoint and examine its total in the page object. Then call the same endpoint a second time, with the limit set to the size of the total.

For example, if needing to retrieve all the cases that a user participated in, then first call:

/api/1.0/workflow/cases/participated/paged

If the page's total is 239, then call the endpoint a second time to retrieve all the cases at once:

/api/1.0/workflow/cases/participated/paged?limit=239

If there is a large number of cases, it may be recommended to download them with multiple calls:

/api/1.0/workflow/cases/participated/paged?start=1&limit=100
/api/1.0/workflow/cases/participated/paged?start=101&limit=100
/api/1.0/workflow/cases/participated/paged?start=201&limit=100


Reading a page of cases with JavaScript:
This example prints out in the <body> of the current web page when each case in the logged-in user's inbox is due:

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

req.onreadystatechange = function() {
   if (req.readyState==4 && req.status==200) {
      //use JSON.parse() to decode string if the web browser supports it:
      var oPageCases = (JSON) ? JSON.parse(req.responseText) : eval(req.responseText);
      var aCases = oPageCases.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 '" + aCases[i].app_title + "' in task '" + aCases[i].app_tas_title +
            "' is due " + aCases[i].del_task_due_date + ".";
         document.body.appendChild(p);
      }
   }
};
reg.send(null);

Reading a page of cases with PHP:
This example prints out when each case in the logged-in user's inbox is due:

$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);
$oPage = json_decode(curl_exec($ch));
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($statusCode == 200) {
   //loop through array of cases and print when each one is due:
   foreach ($oPage->data as $oCase) {
      print "<p>Case '{$oCase->app_title}' in task '{$oCase->app_tas_title}' is due {$oCase->del_task_due_date}.</p>\n";
   }
}

Get To Do Cases: GET /cases

Get the list of To Do cases for the logged in user. Cases with "TO DO" status have been assigned to the user, but the current task in the case hasn't yet been worked on.

GET /api/1.0/{workspace}/cases

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases
filters See Filters for Listing cases. /api/1.0/workflow/cases?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

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" (without hyphens).

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/cases", 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 aCases = (JSON) ? JSON.parse(req.responseText) : eval(req.responseText);

      //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 '" + aCases[i].app_title + "' in task '" + aCases[i].app_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 2015-02-05 17:00:00.
Case '#10' in task 'Company protocol training' was due 2015-02-02 13:16:17.
Case '#7' in task 'Practice safety with trainer' was due 2015-02-02 11:15:14.
Case '#5' in task 'Written safety test' was due 2015-01-30 12:41:35.
Case '#5' in task 'Practice safety with trainer' was due 2015-01-30 12:41:36.
Case '#3' in task 'Practice safety with trainer' was due 2015-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();

$ch = curl_init($apiServer . "/api/1.0/workflow/cases");
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";

   foreach ($aCases 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 2015-02-05 17:00:00.
Case '#10' was due on 2015-02-02 13:16:17.
Case '#7' was due on 2015-02-02 11:15:14.
Case '#5' was due on 2015-01-30 12:41:35.
Case '#5' was due on 2015-01-30 12:41:36.
Case '#3' was due on 2015-01-30 09:45:10.

Get Page of To Do Cases: GET /cases/paged

Get a page of cases with "To do" status for the logged-in user.

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

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/paged
filters See Filters for Listing cases. /api/1.0/workflow/cases/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

JavaScript Example:

This example calls the /cases/paged?limit=0 endpoint to find out how many total cases the logged-in user has in his/her inbox. Then it calls the /cases/paged?limit=X endpoint again to download all the cases at once. It then generates statistics on how many cases are in each task and prints this information in the <body> of the web page.

function printToDoCasesByTask() {
   //call first time to get total number of cases:
   pmEndpoint("GET", "/api/1.0/workflow/cases/paged?limit=0");

   if (oRet) {
      //call second time to download all cases:
      pmEndpoint("GET", "/api/1.0/workflow/cases/paged?limit=" + oRet.total);

      if (oRet) {
         //Create an empty object which will contain the process titles and each process will contain an
         //object holding the task titles and their total number of cases, like this:
         // {
         //    "Process 1": {
         //       "Task X": 3,
         //       "Task Y": 5
         //    }
         //    "Process 2": {
         //       "Task Z": 4
         //    }
         // }
         var oProcesses = new Object();
         var aCases = oRet.data;

         //loop through all the cases and add process titles, task titles and totals to the oProcesses object
         for (var i=0; i < aCases.length; i++) {
            var oCase = aCases[i];

            //if doesn't yet have the process title in oProcesses, then add it:
            if (!oProcesses.hasOwnProperty(aCases[i].app_pro_title))
               oProcesses[oCase.app_pro_title] = {};

            //if doesn't yet have the task title in oProcess.<process-name>, then add it and set count to 1:
            if (!oProcesses[aCases[i].app_pro_title].hasOwnProperty(aCases[i].app_tas_title))
               oProcesses[oCase.app_pro_title][oCase.app_tas_title] = 1;
            else  //if task already exists, then add 1 to its count:
               oProcesses[oCase.app_pro_title][oCase.app_tas_title] += 1;
         }

        //loop through oProcesses and print totals to <body> of web page:
        for (process in oProcesses) {
           totals = "Process '" + process + "':\n<ul>\n";
           for (task in oProcesses[process]) {
              totals += "<li>Task '" + task + "': " + oProcesses[process][task] + "</li>\n";
           }
           var p = document.createElement('p');
           p.innerHTML = totals + "</ul>\n";
           document.body.appendChild(p);
        }
     }
  }
}

printToDoCasesByTask(); //execute function

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

Process 'New employee onboarding':

  • Task 'Company protocol training': 2

Process 'Safety training course':

  • Task 'Practice safety with trainer': 3
  • Task 'Written safety test': 1

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();

$ch = curl_init($apiServer . "/api/1.0/workflow/cases");
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";

   foreach ($aCases 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";
      }
   }
}

Get Draft Cases: GET /cases/draft

Get the list of Draft cases for the logged-in user.

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

Parameters:

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

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned with "DRAFT" status. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 [
    {
    "app_uid": "50576446953235bfb797531078087088",
    "del_index": "1",
    "del_last_index": "1",
    "app_number": "1",
    "app_status": "ID_DRAFT",
    "usr_uid": "00000000000000000000000000000001"
    "previous_usr_uid": "",
    "tas_uid": "7983935495320c1a75e1df6068322280",
    "pro_uid": "2317283235320c1a36972b2028131767",
    "del_delegate_date": "2014-03-14 15:43:55",
    "del_init_date": "2014-03-14 15:43:55",
    "del_task_due_date": "2014-03-17 15:43:55",
    "del_finish_date": null,
    "del_thread_status": "OPEN",
    "app_thread_status": "OPEN",
    "app_title": "#1",
    "app_pro_title": "Invoice Approval Process",
    "app_tas_title": "Task 1",
    "app_current_user": " Administrator",
    "app_del_previous_user": "",
    "del_priority": "ID_PRIORITY_N",
    "del_duration": "0",
    "del_queue_duration": "0",
    "del_delay_duration": "0",
    "del_started": "0",
    "del_finished": "0",
    "del_delayed": "0",
    "app_create_date": "2014-03-14 15:43:55",
    "app_finish_date": null,
    "app_update_date": "2014-03-14 15:43:57",
    "app_overdue_percentage": "0",
    "usr_firstname": "Administrator",
    "usr_lastname": " ",
    "usr_username": "admin",
    "appcvcr_app_tas_title": "Task 1",
    "usrcr_usr_uid": "00000000000000000000000000000001",
    "usrcr_usr_firstname": "Administrator",
    "usrcr_usr_lastname": " ",
    "usrcr_usr_username": "admin"
    }
 ]

Get Page of Draft Cases: GET /cases/draft/paged

Get a page of Draft cases for the logged-in user.

GET /api/1.0/{workspace}/cases/draft/paged

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/draft/paged
filters See Filters for Listing cases. /api/1.0/workflow/cases/draft/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 {
    "start": 0,
    "limit": 1,
    "total": 25,
    "process": "",
    "category": "",
    "search": "",
    "data": [
        {
            "app_uid": "50576446953235bfb797531078087088",
            "del_index": "1",
            "del_last_index": "1",
            "app_number": "1",
            "app_status": "ID_DRAFT",
            "usr_uid": "00000000000000000000000000000001",
            "previous_usr_uid": "",
            "tas_uid": "7983935495320c1a75e1df6068322280",
            "pro_uid": "2317283235320c1a36972b2028131767",
            "del_delegate_date": "2014-03-14 15:43:55",
            "del_init_date": "2014-03-14 15:43:55",
            "del_task_due_date": "2014-03-17 15:43:55",
            "del_finish_date": null,
            "del_thread_status": "OPEN",
            "app_thread_status": "OPEN",
            "app_title": "#1",
            "app_pro_title": "Invoice Approval Process",
            "app_tas_title": "Task 1",
            "app_current_user": " Administrator",
            "app_del_previous_user": "",
            "del_priority": "ID_PRIORITY_N",
            "del_duration": "0",
            "del_queue_duration": "0",
            "del_delay_duration": "0",
            "del_started": "0",
            "del_finished": "0",
            "del_delayed": "0",
            "app_create_date": "2014-03-14 15:43:55",
            "app_finish_date": null,
            "app_update_date": "2014-03-14 15:43:57",
            "app_overdue_percentage": "0",
            "usr_firstname": "Administrator",
            "usr_lastname": " ",
            "usr_username": "admin",
            "appcvcr_app_tas_title": "Task 1",
            "usrcr_usr_uid": "00000000000000000000000000000001",
            "usrcr_usr_firstname": "Administrator",
            "usrcr_usr_lastname": " ",
            "usrcr_usr_username": "admin"
          }
      ]
 }

Get Participated Cases: GET /cases/participated

Get the list of cases in which the logged in user has participated.

GET /api/1.0/{workspace}/cases/participated
Function: getList makes the request to obtain data from all cases.

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/participated
filters See Filters for Listing cases. /api/1.0/workflow/cases/participated?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 [
    {
        "app_uid": "50576446953235bfb797531078087088",
        "del_index": "1",
        "del_last_index": "1",
        "app_number": "1",
        "app_status": "ID_DRAFT",
        "usr_uid": "00000000000000000000000000000001",
        "previous_usr_uid": "",
        "tas_uid": "7983935495320c1a75e1df6068322280",
        "pro_uid": "2317283235320c1a36972b2028131767",
        "del_delegate_date": "2014-03-14 15:43:55",
        "del_init_date": "2014-03-14 15:43:55",
        "del_task_due_date": "2014-03-17 15:43:55",
        "del_finish_date": null,
        "del_thread_status": "OPEN",
        "app_thread_status": "OPEN",
        "app_title": "#1",
        "app_pro_title": "My process title",
        "app_tas_title": "Task 1",
        "app_current_user": " Administrator",
        "app_del_previous_user": "",
        "del_duration": "0",
        "del_queue_duration": "0",
        "del_delay_duration": "0",
        "del_started": "0",
        "del_finished": "0",
        "del_delayed": "0",
        "app_create_date": "2014-03-14 15:43:55",
        "app_finish_date": null,
        "app_update_date": "2014-03-14 15:43:57",
        "app_overdue_percentage": "0",
        "usr_firstname": "Administrator",
        "usr_lastname": " ",
        "usr_username": "admin",
        "appcvcr_app_tas_title": "Task 1",
        "usrcr_usr_uid": "00000000000000000000000000000001",
        "usrcr_usr_firstname": "Administrator",
        "usrcr_usr_lastname": " ",
        "usrcr_usr_username": "admin"
    }
]

Get Page of Participated Cases: GET /cases/participated/paged

Get a page the cases in which the logged-in user has participated.

GET /api/1.0/{workspace}/cases/participated/paged
Function: getList makes the request to obtain data from all cases.

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/participated/paged
filters See Filters for Listing cases. /api/1.0/workflow/cases/participated/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 {
    "start": 0,
    "limit": 1,
    "total": 25,
    "process": "",
    "category": "",
    "search": "",
    "data": [
        {
            "app_uid": "50576446953235bfb797531078087088",
            "del_index": "1",
            "del_last_index": "1",
            "app_number": "1",
            "app_status": "ID_DRAFT",
            "usr_uid": "00000000000000000000000000000001",
            "previous_usr_uid": "",
            "tas_uid": "7983935495320c1a75e1df6068322280",
            "pro_uid": "2317283235320c1a36972b2028131767",
            "del_delegate_date": "2014-03-14 15:43:55",
            "del_init_date": "2014-03-14 15:43:55",
            "del_task_due_date": "2014-03-17 15:43:55",
            "del_finish_date": null,
            "del_thread_status": "OPEN",
            "app_thread_status": "OPEN",
            "app_title": "#1",
            "app_pro_title": "Invoice Approval Process",
            "app_tas_title": "Task 1",
            "app_current_user": " Administrator",
            "app_del_previous_user": "",
            "del_duration": "0",
            "del_queue_duration": "0",
            "del_delay_duration": "0",
            "del_started": "0",
            "del_finished": "0",
            "del_delayed": "0",
            "app_create_date": "2014-03-14 15:43:55",
            "app_finish_date": null,
            "app_update_date": "2014-03-14 15:43:57",
            "app_overdue_percentage": "0",
            "usr_firstname": "Administrator",
            "usr_lastname": " ",
            "usr_username": "admin",
            "appcvcr_app_tas_title": "Task 1",
            "usrcr_usr_uid": "00000000000000000000000000000001",
            "usrcr_usr_firstname": "Administrator",
            "usrcr_usr_lastname": " ",
            "usrcr_usr_username": "admin"
            }
        ]
 }

Get Unassigned Cases: GET /cases/unassigned

Get the list of Unassigned cases, which the logged-in user may claim (i.e., assign to him/herself to work on). These are cases whose current task have a self-service assignment rule, but have not yet been claimed by any user. Note: In order to claim a case, the logged-in user must either be assigned as a user or an ad hoc user to the case's current task.

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

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/unassigned
filters See Filters for Listing cases. /api/1.0/workflow/cases/unassigned?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 [
    {
        "app_uid": "50576446953235bfb797531078087088",
        "del_index": "1",
        "del_last_index": "1",
        "app_number": "1",
        "app_status": "ID_TODO",
        "usr_uid": "00000000000000000000000000000001",
        "previous_usr_uid": "",
        "tas_uid": "7983935495320c1a75e1df6068322280",
        "pro_uid": "2317283235320c1a36972b2028131767",
        "del_delegate_date": "2014-03-14 15:43:55",
        "del_init_date": "2014-03-14 15:43:55",
        "del_task_due_date": "2014-03-17 15:43:55",
        "del_finish_date": null,
        "del_thread_status": "OPEN",
        "app_thread_status": "OPEN",
        "app_title": "#1",
        "app_pro_title": "my process title",
        "app_tas_title": "Task 1",
        "app_del_previous_user": "",
        "del_duration": "0",
        "del_queue_duration": "0",
        "del_delay_duration": "0",
        "del_started": "0",
        "del_finished": "0",
        "del_delayed": "0",
        "app_create_date": "2014-03-14 15:43:55",
        "app_finish_date": null,
        "app_update_date": "2014-03-14 15:43:57",
        "app_overdue_percentage": "0",
        "appcvcr_app_tas_title": "Task 1"
    }
]

Get Page of Unassigned Cases: GET /cases/unassigned/paged

Get a page of Unassigned cases, which the logged-in user may claim (i.e., assign to him/herself to work on). These are cases whose current task have a self-service assignment rule, but have not yet been claimed by any user. Note: In order to claim a case, the logged-in user must either be assigned as a user or an ad hoc user to the case's current task.

GET /api/1.0/{workspace}/cases/unassigned/paged

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/unassigned/paged
filters See Filters for Listing cases. /api/1.0/workflow/cases/unassigned/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 {
    "start": 0,
    "limit": 1,
    "total": 25,
    "process": "",
    "category": "",
    "search": "",
    "data": [
        {
            "app_uid": "50576446953235bfb797531078087088",
            "del_index": "1",
            "del_last_index": "1",
            "app_number": "1",
            "app_status": "ID_TODO",
            "usr_uid": "00000000000000000000000000000001",
            "previous_usr_uid": "",
            "tas_uid": "7983935495320c1a75e1df6068322280",
            "pro_uid": "2317283235320c1a36972b2028131767",
            "del_delegate_date": "2014-03-14 15:43:55",
            "del_init_date": "2014-03-14 15:43:55",
            "del_task_due_date": "2014-03-17 15:43:55",
            "del_finish_date": null,
            "del_thread_status": "OPEN",
            "app_thread_status": "OPEN",
            "app_title": "#1",
            "app_pro_title": "Invoice Approval Process",
            "app_tas_title": "Task 1",
            "app_del_previous_user": "",
            "del_duration": "0",
            "del_queue_duration": "0",
            "del_delay_duration": "0",
            "del_started": "0",
            "del_finished": "0",
            "del_delayed": "0",
            "app_create_date": "2014-03-14 15:43:55",
            "app_finish_date": null,
            "app_update_date": "2014-03-14 15:43:57",
            "app_overdue_percentage": "0",
            }
        ]
  }

Get Paused Cases: GET /cases/paused

Get a list of Paused cases which are assigned to the logged-in user.

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

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/paused
filters See Filters for Listing cases. /api/1.0/workflow/cases/paused?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a array of case objects is returned. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

PHP Example:

$oRet = pmRestRequest("GET", '/api/1.0/workflow/cases/paged');
if ($oRet->status == 200) {
   if (!empty($oRet->response)) {
      print "Paused cases:\n";
      foreach ($oRet->response as $oCase) {
         print "Case {$oCase->app_name} was started by {$oCase->app_init_usr_username} " .
            "on {$oCase->app_create_date} and was last updated on {$oCase->app_update_date}\n";
      }
   }
   else {
      print "There are no paused cases.\n";
   }
}

Get Page of Paused Cases: GET /cases/paused/paged

Get a page of Paused cases assigned to the logged-in user.

GET /api/1.0/{workspace}/cases/paused/paged

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/paused/paged
filters See Filters for Listing cases. /api/1.0/workflow/cases/paused/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 {
    "start": 0,
    "limit": 1,
    "total": 25,
    "process": "",
    "category": "",
    "search": "",
    "data": [
        {
            "app_uid": "50576446953235bfb797531078087088",
            "del_index": "1",
            "del_last_index": "1",
            "app_number": "1",
            "app_status": "ID_TODO",
            "usr_uid": "00000000000000000000000000000001",
            "previous_usr_uid": "",
            "tas_uid": "7983935495320c1a75e1df6068322280",
            "pro_uid": "2317283235320c1a36972b2028131767",
            "del_delegate_date": "2014-03-14 15:43:55",
            "del_init_date": "2014-03-14 15:43:55",
            "del_task_due_date": "2014-03-17 15:43:55",
            "del_finish_date": null,
            "del_thread_status": "OPEN",
            "app_thread_status": "OPEN",
            "app_title": "#1",
            "app_pro_title": "Invoice Approval Process",
            "app_tas_title": "Task 1",
            "app_current_user": " Administrator",
            "app_del_previous_user": "",
            "del_duration": "0",
            "del_queue_duration": "0",
            "del_delay_duration": "0",
            "del_started": "0",
            "del_finished": "0",
            "del_delayed": "0",
            "app_create_date": "2014-03-14 15:43:55",
            "app_finish_date": null,
            "app_update_date": "2014-03-14 15:43:57",
            "app_overdue_percentage": "0",
            "usr_firstname": "Administrator",
            "usr_lastname": " ",
            "usr_username": "admin",
            "appcvcr_app_tas_title": "Task 1",
            "usrcr_usr_uid": "00000000000000000000000000000001",
            "usrcr_usr_firstname": "Administrator",
            "usrcr_usr_lastname": " ",
            "usrcr_usr_username": "admin"
            }
        ]
 }

Get Advanced Search Cases: GET /cases/advanced-search

Get a list of cases obtained with advanced search. Unlike the other GET /cases... endpoints, /cases/advanced-search returns all the cases in the workspace which meet the search criteria, including cases to which the logged-in user is not assigned.

GET /api/1.0/{workspace}/cases/advanced-search

Warning: If the logged-in user does not have the PM_ALLCASES permission in his/her role, this endpoint only gets cases in which the user has participated, has process permissions or is assigned as a process supervisor.

Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/advanced-search
app_status Optional. Case status which can be "TO_DO", "DRAFT", "PAUSED", "CANCELLED", or "COMPLETED" /api/1.0/workflow/cases/advanced-search?app_status=CANCELLED
usr_uid Optional. Unique ID of the user who is currently assigned to the case. /api/1.0/workflow/cases/advanced-search?usr_uid=29131200354d248b15df286060262849
date_from Optional. Search for cases which were routed to their current task on or after this date in 'YYYY-MM-DD' format. /api/1.0/workflow/cases/advanced-search?date_from=2013-01-31
date_to Optional. Search for cases which were routed to their current task on or before this date in 'YYYY-MM-DD' format. /api/1.0/workflow/cases/advanced-search?date_to=2015-01-31
filters Optional. See the standard Filters for Listing cases. /api/1.0/workflow/cases/advanced-search?search=training

Result:

If a successful, then the HTTP status code is set to 200 and an array of case objects is returned. 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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

Example:

Response

 200(OK)
 Content-Type: application/json
 [
        {
            "app_uid": "50576446953235bfb797531078087088",
            "del_index": "1",
            "del_last_index": "1",
            "app_number": "1",
            "app_status": "**ID_DRAFT**",
            "usr_uid": "00000000000000000000000000000001",
            "previous_usr_uid": "",
            "tas_uid": "7983935495320c1a75e1df6068322280",
            "pro_uid": "2317283235320c1a36972b2028131767",
            "del_delegate_date": "2014-03-14 15:43:55",
            "del_init_date": "2014-03-14 15:43:55",
            "del_task_due_date": "2014-03-17 15:43:55",
            "del_finish_date": null,
            "del_thread_status": "OPEN",
            "app_thread_status": "OPEN",
            "app_title": "#1",
            "app_pro_title": "Invoice Approval Process",
            "app_tas_title": "Task 1",
            "app_current_user": " Administrator",
            "app_del_previous_user": "",
            "del_duration": "0",
            "del_queue_duration": "0",
            "del_delay_duration": "0",
            "del_started": "0",
            "del_finished": "0",
            "del_delayed": "0",
            "app_create_date": "2014-03-14 15:43:55",
            "app_finish_date": null,
            "app_update_date": "2014-03-14 15:43:57",
            "app_overdue_percentage": "0",
            "usr_firstname": "Administrator",
            "usr_lastname": " ",
            "usr_username": "admin",
            "appcvcr_app_tas_title": "Task 1",
            "usrcr_usr_uid": "00000000000000000000000000000001",
            "usrcr_usr_firstname": "Administrator",
            "usrcr_usr_lastname": " ",
            "usrcr_usr_username": "admin"
        }
    ]

Get Page of Advanced Search Cases: GET /cases/advanced-search/paged

Get a page of cases obtained with advanced search. Unlike the other GET /cases... endpoints, /cases/advanced-search/paged returns all the cases in the workspace which meet the search criteria, including cases to which the logged-in user is not assigned.

GET /api/1.0/{workspace}/cases/advanced-search/paged

Warning: If the logged-in user does not have the PM_ALLCASES permission in his/her role, this endpoint only gets cases in which the user has participated, has process permissions or is assigned as a process supervisor.

URL Parameters:

Parameter Description Example
{workspace} Workspace name. /api/1.0/workflow/cases/advanced-search/paged
app_status Optional. Case status which can be "TO_DO", "DRAFT", "PAUSED", "CANCELLED", or "COMPLETED" /api/1.0/workflow/cases/advanced-search/paged?app_status=CANCELLED
usr_uid Optional. Unique ID of the user who is currently assigned to the case. /api/1.0/workflow/cases/advanced-search/paged?usr_uid=29131200354d248b15df286060262849
date_from Optional. Search for cases which were routed to their current task on or after this date in 'YYYY-MM-DD' format. /api/1.0/workflow/cases/advanced-search/paged?date_from=2013-01-31
date_to Optional. Search for cases which were routed to their current task on or before this date in 'YYYY-MM-DD' format. /api/1.0/workflow/cases/advanced-search/paged?date_to=2015-01-31
filters Optional. See the standard Filters for Listing cases. /api/1.0/workflow/cases/advanced-search/paged?search=training

Result:

If a successful, then the HTTP status code is set to 200 and a page is returned with an array of case objects in its data member. Unlike a normal page of cases, the object includes the additional members app_status, usr_uid, date_from and date_to. For example:

 200(OK)
 Content-Type: application/json
 {
    "total":      1,
    "start":      1,
    "limit":      25,
    "sort":       "app_cache_view.app_number",
    "dir":        "desc",
    "cat_uid":    "",
    "pro_uid":    "",
    "search":     "",
    "app_status": "",
    "usr_uid":    "",
    "date_from":  "",
    "date_to":    "",
    "data": [
       {
          "app_uid":                "50576446953235bfb797531078087088",
          "del_index":              "1",
          "del_last_index":         "1",
          "app_number":             "1",
          "app_status":             "TO_DO",
          "usr_uid":                "00000000000000000000000000000001",
          "previous_usr_uid":       "",
          "tas_uid":                "7983935495320c1a75e1df6068322280",
          "pro_uid":                "2317283235320c1a36972b2028131767",
          "del_delegate_date":      "2014-03-14 15:43:55",
          "del_init_date":          "2014-03-14 15:43:55",
          "del_task_due_date":      "2014-03-17 15:43:55",
          "del_finish_date":        null,
          "del_thread_status":      "OPEN",
          "app_thread_status":      "OPEN",
          "app_title":              "#1",
          "app_pro_title":          "Invoice Approval Process",
          "app_tas_title":          "Task 1",
          "app_current_user":       " Administrator",
          "app_del_previous_user":  "",
          "del_duration":           "0",
          "del_queue_duration":     "0",
          "del_delay_duration":     "0",
          "del_started":            "0",
          "del_finished":           "0",
          "del_delayed":            "0",
          "app_create_date":        "2014-03-14 15:43:55",
          "app_finish_date":        null,
          "app_update_date":        "2014-03-14 15:43:57",
          "app_overdue_percentage": "0",
          "usr_firstname":          "Administrator",
          "usr_lastname":           " ",
          "usr_username":           "admin",
          "appcvcr_app_tas_title":  "Task 1",
          "usrcr_usr_uid":         "00000000000000000000000000000001",
          "usrcr_usr_firstname":   "Administrator",
          "usrcr_usr_lastname":    " ",
          "usrcr_usr_username":    "admin",
          "app_status_label":      "To do"
       }
    ]
}

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 category with $cat_uid: '93718116854ca5884585758048057153' does not exist."
   }
}

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. Note that if this endpoint is called for a case that has already been completed, then there is no current task and an error will be returned. Note that the logged-in user must either be currently assigned to work on the case or have Process Permissions to access the task(s).

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-in user is assigned. This endpoint can be called to discover to the processes and tasks where the logged-in 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-in user to work on the initial task in the case. Note that the logged-in 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-in 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-in 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-in 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-in 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";
}