Overview

This documentation covers the following endpoints in the ProcessMaker REST API 1.0, which deal with accessing and executing cases:

Contents: [hide]
  1. Overview
  2. Cases
    1. Filters for listing cases
    2. Calling /cases endpoints
      1. Case Object
      2. Returning a list of cases
      3. Returning a page of cases
    3. Get To Do Cases: GET /cases
    4. Get Page of To Do Cases: GET /cases/paged
    5. Get Draft Cases: GET /cases/draft
    6. Get Page of Draft Cases: GET /cases/draft/paged
    7. Get Participated Cases: GET /cases/participated
    8. Get Page of Participated Cases: GET /cases/participated/paged
    9. Get Unassigned Cases: GET /cases/unassigned
    10. Get Page of Unassigned Cases: GET /cases/unassigned/paged
    11. Get Paused Cases: GET /cases/paused
    12. Get Page of Paused Cases: GET /cases/paused/paged
    13. Get Advanced Search Cases: GET /cases/advanced-search
    14. Get Page of Advanced Search Cases: GET /cases/advanced-search/paged
    15. Get Case Information: GET /cases/{app_uid}
    16. Get Case's Current Tasks: GET /cases/{app_uid}/current-task
    17. Get Case's Tasks: GET /cases/{app_uid}/tasks
    18. Get Starting Tasks: GET /case/start-cases
    19. New Case: POST /cases
      1. Format of Variables
    20. New Case Impersonate: POST /cases/impersonate
    21. Reassign Case: PUT /cases/{app_uid}/reassign-case
    22. Batch Reassigning Cases: POST /cases/reassign
    23. Route Case: PUT /cases/{app_uid}/route-case
    24. Cancel Case: PUT /cases/{app_uid}/cancel
    25. Pause Case: PUT /cases/{app_uid}/pause
    26. Unpause Case: PUT /cases/{app_uid}/unpause
    27. Execute Trigger: PUT /cases/{app_uid}/execute-trigger/{tri_uid}
    28. Delete Case: DELETE /cases/{app_uid}
  3. Case Variables
    1. Get Variables: GET /cases/{app_uid}/variables
    2. Set Variables: PUT /cases/{app_uid}/variable
    3. Get Case Variable: GET /case/{app_uid}/{del_index}/variable/{var_name}
    4. Get Page of Grid Variable: GET /case/{app_uid}/{del_index}/variable/{var_name}/paged
    5. Create Variable: POST /cases/{app_uid}/{del_index}/variable/{var_name}
    6. Update Variable: PUT /cases/{app_uid}/{del_index}/variable/{var_name}
    7. Delete Variable: DELETE /cases/{app_uid}/{del_index}/variable/{var_name}
  4. Input Documents
    1. Get a list of Input Documents: GET /cases/{app_uid}/input-documents
    2. Get Input Document Information: GET /cases/{app_uid}/input-document/{app_doc_uid}
    3. Upload Input Document: POST /cases/{app_uid}/input-document
    4. Download an Input Document: GET /cases/{app_uid}/input-document/{app_doc_uid}/file?v={version}
    5. Delete Input Document: DELETE /cases/{app_uid}/{del_index}/input-document/{app_doc_uid}
  5. Output Documents
    1. Get Output Documents: GET /cases/{app_uid}/output-documents
    2. Get Output Document: GET /cases/{app_uid}/output-document/{app_doc_uid}
    3. Generate Output Document: POST /cases/{app_uid}/{del_index}/output-document/{app_doc_uid} (>= version 3.0.0.5)
    4. Generate Output Document: POST /cases/{app_uid}/output-document (<= version 3.0.0.4)
    5. Delete Output Document: DELETE /cases/{app_uid}/output-document/{app_doc_uid}
  6. Cases Notes
    1. Get Case Notes: GET /cases/{app_uid}/notes
    2. Get Page of Case Notes: GET /cases/{app_uid}/notes/paged
    3. Create Case Note: POST /cases/{app_uid}/note
  7. Mobile Endpoints
    1. Create case file record(s): POST /light/case/{app_uid}/upload

Cases

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

  1. Get To Do Cases: GET /cases
  2. Get Page of To Do Cases: GET /cases/paged
  3. Get Draft Cases: GET /cases/draft
  4. Get Page of Draft Cases: GET /cases/draft/paged
  5. Get Participated Cases: GET /cases/participated
  6. Get Page of Participated Cases: GET /cases/participated/paged
  7. Get Unassigned Cases: GET /cases/unassigned
  8. Get Page of Unassigned Cases: GET /cases/unassigned/paged
  9. Get Paused Cases: GET /cases/paused
  10. Get Page of Paused Cases: GET /cases/paused/paged
  11. Get Advanced Search Cases: GET /cases/advanced-search
  12. Get Page of Advanced Search Cases: GET /cases/advanced-search/paged
  13. Get Case Information: GET /cases/{app_uid}
  14. Get Case's Current Task(s): GET /cases/{app_uid}/current-task
  15. Get Case's Tasks: GET /cases/{app_uid}/tasks (Version 3.0 and later.)
  16. Get Starting Tasks: GET /case/start-cases
  17. New Case: POST /cases
  18. New Case Impersonate: POST /cases/impersonate
  19. Reassign Case: PUT /cases/{app_uid}/reassign-case
  20. Route Case: PUT /cases/{app_uid}/route-case
  21. Cancel Case: PUT /cases/{app_uid}/cancel
  22. Pause Case: PUT /cases/{app_uid}/pause
  23. Unpause Case: PUT /cases/{app_uid}/unpause
  24. Execute Trigger: PUT /cases/{app_uid}/execute-trigger/{tri_uid}
  25. Delete Case: DELETE /cases/{app_uid}

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:

ParameterDescriptionDefault valueExample
start={number}The number of cases where the list begins. If set to 0 or 1, then begins with the first case. 2 begins with the second case, 3 begins with 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 CON_ID, CON_VALUE FROM CONTENT WHERE CON_CATEGORY='PRO_TITLE';
/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:

ElementDescriptionExample
{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:

ElementDescription
{
"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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/paged
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/draft
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/draft/paged
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/participated
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/participated/paged
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/unassigned
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/unassigned/paged
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/paused
filtersSee 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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/paused/paged
filtersSee 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: The logged-in user must have the PM_ALLCASES permission assigned to their role to be able to use this endpoint.

Parameters:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/advanced-search
app_statusOptional. Case status which can be "TO_DO", "DRAFT", "PAUSED", "CANCELLED", or "COMPLETED"/api/1.0/workflow/cases/advanced-search?app_status=CANCELLED
usr_uidOptional. Unique ID of the user who is currently assigned to the case./api/1.0/workflow/cases/advanced-search?usr_uid=29131200354d248b15df286060262849
date_fromOptional. 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_toOptional. 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
filtersOptional. 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 should only be able to search for cases in which the user has participated, has process permissions or is assigned as a process supervisor.

URL Parameters:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/advanced-search/paged
app_statusOptional. Case status which can be "TO_DO", "DRAFT", "PAUSED", "CANCELLED", or "COMPLETED"/api/1.0/workflow/cases/advanced-search/paged?app_status=CANCELLED
usr_uidOptional. Unique ID of the user who is currently assigned to the case./api/1.0/workflow/cases/advanced-search/paged?usr_uid=29131200354d248b15df286060262849
date_fromOptional. 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_toOptional. 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
filtersOptional. 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.

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

Parameters:

ParameterDescriptionExample
{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:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/cases/37213410154d375de3e3620044382558/current-task
app_uidCase'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. Available in version 3.0 and later.

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:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/cases/37213410154d375de3e3620044382558/tasks
app_uidCase'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 task
"usr_username": Username of user assigned to work on task
"usr_firstname": First name of user assigned to work on task
"usr_lastname": Last name of user assigned to work on task
"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",
      "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",
      "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"
   }            
]

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:

ParameterDescriptionExample
{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 elementDescription
[ 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"
  }
]

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.

POST /api/1.0/{workspace}/cases

URL Parameters:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases

POST Parameters:

ParameterTypeDescriptionExample
pro_uidStringUnique ID of process/project."11703471254f718165880f2035616306"
tas_uidStringUnique ID of the initial task to start the case. This should be a task with a start event."33432552454f5c38aa3a620081949840"
variablesArrayOptional. 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.
[{
  "client": "Acme Inc.",
  "amount": 23456.99,
  "dateDue": "2015-12-31 23:59:59",
  "contractCheckbox": ["1"],
  "contactCheckgroup": ["fax","email","phone"]
}]

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: [ { "variable1": "value1", "variable2": "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";
}

New Case Impersonate: POST /cases/impersonate

Creates a new case. It is similar to POST /cases, but it 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.

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

URL Parameters:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/impersonate

POST Parameters:

ParameterTypeDescriptionExample
pro_uidStringUnique ID of process/project."11703471254f718165880f2035616306"
usr_uidStringUnique ID of user who will be assigned to initial task in case."51382566154f7180953b5e1028461947"
tas_uidStringUnique ID of the initial task to start the case. This should be a task with a start event."33432552454f5c38aa3a620081949840"
variablesArrayOptional. Variables that are set in the new case. See New Case: POST /cases for more information. [{"client": "Acme Inc.", "amount": 23456.99}]


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/case";
$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. Note that the logged-in user needs to have the PM_REASSIGNCASE permission in his/her role in order to be able to reassign the case.

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

URL Parameters:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/55324179754ca442baeb994077387342/reassign-case
app_uidCase's unique ID./api/1.0/workflow/cases/55324179754ca442baeb994077387342/reassign-case

PUT Parameters:

ParameterTypeDescriptionExample
usr_uid_sourceStringRequired. Unique ID of user currently assigned to case."41089101154de3b97536fc0077548396"
usr_uid_targetStringRequired. 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"

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. Note that the logged-in user needs to be Supervisor of the processes to which the cases belong to or needs to have the PM_REASSIGNCASE permission in his/her role in order to be able to reassign the cases.

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

URL Parameters:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/reassign

POST Parameters:

ParameterTypeDescriptionExample
APP_UIDStringRequired. Unique ID of the case."775512695580a23a40d7bb6035424645"
DEL_INDEXIntegerRequired. 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_targetStringRequired. 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\"
        }
    }
}"

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

{
    "cases": [
    {
        "app_uid": "175994873580a23f3da1670048245491",
        "del_index": 2,
        "result": 0,
        "status": "DELEGATION_NOT_EXISTS"
    }
    ]
}
{
    "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.

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:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/55324179754ca442baeb994077387342/route-case
app_uidCase's unique ID./api/1.0/workflow/cases/55324179754ca442baeb994077387342/route-case

PUT Parameters:

ParameterDescription
del_indexOptional. 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.

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

Cancel a case. The case's status is changed to "CANCELLED" and it is no longer possible to open or changed the case, but all the data for the case remain in the database.

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

Warning: The logged-in user should only be able to cancel a case if he/she is the the currently assigned user to the case or the logged-in user has the PM_CANCELCASE permission in his/her role.

Parameters:

ParameterDescriptionExample
{workspace}Workspace name./api/1.0/workflow/cases/55324179754ca442baeb994077387342/cancel
app_uidCase'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.

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

Warning: In order 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:

ParameterDescriptionExample
workspaceWorkspace name./api/1.0/workflow/cases/55324179754ca442baeb994077387342/pause
app_uidCase's unique ID./api/1.0/workflow/cases/55324179754ca442baeb994077387342/pause

PUT Parameters:

ParameterDescriptionExample
unpaused_dateDate 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.

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:

ParameterDescriptionExample
workspaceWorkspace name./api/1.0/workflow/cases/55324179754ca442baeb994077387342/unpause
app_uidCase's unique ID./api/1.0/workflow/cases/55324179754ca442baeb994077387342/unpause


PUT Parameters:

ParameterDescriptionExample
unpaused_dateOptional. 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.

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

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name./api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674
app_uidUnique ID of the case where the trigger will be executed./api/1.0/workflow/cases/55324179754ca442baeb994077387342/execute-trigger/11985271254f9b9ff1319c2032433674
tri_uidUnique 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;
      }
   }
}

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.

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

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/cases/37213410154d375de3e3620044382558
app_uidCase'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";
}

Case Variables

These endpoints get or set the variables for a given case. Use the GET method to obtain the variables from a case and the PUT method to set variables in a case.

Get Variables: GET /cases/{app_uid}/variables

Get variables from a case. Note that this endpoint can return the variables from any case, regardless of its status, so it can get the variables for paused, completed or even canceled cases. The only cases for which it can't get the variables are deleted cases, because their records has been removed from the APPLICATION table in the database.

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

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/cases/37213410154d375de3e3620044382558/variables
app_uidCase's unique ID./api/1.0/workflow/cases/37213410154d375de3e3620044382558/variables

Result:
If successful, then returns HTTP status code of 200 (OK) and returns an object of variables, such as:

{
   "SYS_LANG":            "en",
   "SYS_SKIN":            "neoclassic",
   "SYS_SYS":             "workflow",
   "APPLICATION":         "78484118955bbd5fc39e5c5072875367",
   "PROCESS":             "189248173559579a84bf665046423742",
   "TASK":                "37438452555b10cffda9428064171274",
   "INDEX":               "2",
   "USER_LOGGED":         "00000000000000000000000000000001",
   "USR_USERNAME":        "admin",
   "PIN":                 "JQN",
   "contractor":          "Reliant Parts", //textbox with string variable
   "contractor_label":    "Reliant Parts",
   "sendContract":        "1",             //dropdown with boolean variable
   "sendContract_label":  "Yes",
   "contractReview":      ["0"],           //checkbox with boolean variable
   "contractReview_label":"Rejected",
   "amount":              "45323.50",      //textbox with float variable
   "amount_label":        "45323.50",
   "dueDate":             "2016-03-19",    //datetime
   "dueDate_label":       "03/19/2016",
   "markToReview":        ["contract", "credit", "comments"], //checkbox group with string variable
   "markToReview_label":  '["Contract", "Credit History", "Past Comments"]',
   "reviewerList":        {                //grid with textbox and checkbox fields
      "1": {"name": "Betty Blue", "name_label": "Betty Blue", "approved": "1", "approved_label": "Yes"},
      "2": {"name": "Bill Houck", "name_label": "Bill Houck", "approved": "0", "approved_label": "No"},
      "3": {"name": "Mae Sander", "name_label": "Mae Sander", "approved": "1", "approved_label": "Yes"}
    }
}

Note: DynaForm fields which have integer or float variables have their values stored as strings, so it may be necessary to convert their values to numbers if doing mathematical operations. Grids and the results of database queries are stored as an associative array of associative arrays in ProcessMaker, but they are converted into an object of objects, because JSON doesn't support associative arrays.

When reading this object of objects in PHP, it is recommended to either use json_decode($json, true) to convert the return object into an associative array or get_object_vars() to convert the rows in a grid to an associative array. See the example below.

PHP Example:

This example, using the case variables returned in the example, converts the "reviewersList" grid from an object to an associative array and then loops through that array to print out the names of the reviewers and their decision to approve or disapprove the contract.

$caseId = '78484118955bbd5fc39e5c5072875367';
$url = "/api/1.0/workflow/cases/$caseId/variables";
$method = "GET";
$oRet = pmRestRequest($method, $url);
if ($oRet->status == 200) {
   $oVars = $oRet->response;
   //convert grid from object to associative array:
   $oVars->reviewerList = get_object_vars($oVars->reviewerList);
   echo "Contractor: {$oVars->contractor}\nAmount: {$oVars->amount}\nReviewers:\n";
   
   for ($i = 1; $i <= count($oVars->reviewerList); $i++) {
      echo "$i. {$oVars->reviewerList[$i]->name}: {$oVars->reviewerList[$i]->approved_label}\n";
   }
}  

Set Variables: PUT /cases/{app_uid}/variable

Set variable(s) in a case.

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

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/cases/37213410154d375de3e3620044382558/variable
app_uidCase's unique ID./api/1.0/workflow/cases/37213410154d375de3e3620044382558/variable

PUT Parameters:

A object where the name of each element is the variable name and its value will be the new value of the case variable in the specified case. If the variable doesn't already exist, it will be automatically created. See New Case: POST /cases for more information on how to set the values of different types of fields.

Result:
If successful, sets the HTTP status code to 200 (OK) and there is no return object. 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 application with $app_uid: '78484118955bbd5fc39e5c5072875368' does not exist."
   }
}

Note: It is not possible to remove an existing variable using this endpoint, so it is recommended to instead set the variable to "" (an empty string). If needing to completely remove an variable, the only way to do that is to execute a trigger which unsets the variable: unset(@@my_var);
Another way to unset the variable is to remove the variable from the serialized string of variables stored in the wf_{WORKSPACE}.APPLICATION.APP_DATA field in the database. The following PHP code can unset the @@my_var outside a trigger:

$caseId = "37213410154d375de3e3620044382558";
//set to server address, mysql user and mysql password:
$link = mysql_connect('localhost', 'root', 'p4sSw0rd') or die(mysql_error());
//set to workspace database:
mysql_select_db('wf_workflow', $link) or die(mysql_error());
$result = mysql_query("select APP_DATA from APPLICATION where APP_UID = '$caseId'") or
   die(mysql_error());
$row = mysql_fetch_array($result) or die("Unable to fetch data for case $caseId");
$aVars = unserialize($row['APP_DATA']);
unset($aVars['my_var']);
$sVars = mysql_real_escape_string(serialize($aVars));
$result = mysql_query("update APPLICATION set APP_DATA = '$sVars' where APP_UID = '$caseId'") or
  die(mysql_error());
mysql_close($link);

JavaScript example:

var oVars = {
   "clientName"      : "Kelly Cline",      //textbox with string variable
   "quantity"        : 56789,              //textbox with integer variable
   "amount"          : 12249.99,           //textbox with floating point variable
   "makeContact"     : ["1"],              //checkbox with boolean variable
   "howContact"      : ["email", "fax"],   //checkbox group with string variable
   "howContact_label": '["E-mail", "Fax"]',//labels of selected options in JSON string
   "payNow"          : "0",                //dropdown with boolean variable
   "howPay"          : "credit_card",      //dropdown with string variable
   "howPay_label"    : "Credit Card",      //label of selected option in dropdown
   "serviceDue"      : "2015-12-31",       //datetime
   "subcontractors"  : {                   //grid
      "1": {"name": "Smith & Wright",   "hasContract": "0"},
      "2": {"name": "A+ Lawn Services", "hasContract": "1"}
   }
};
var caseId = '78484118955bbd5fc39e5c5072875367';
var url = "/api/1.0/workflow/cases/" + caseId + "/variable";
pmRestRequest("PUT", url, oVars, false);

PHP example:

$aVars = 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')
   )
);  
$caseId = '78484118955bbd5fc39e5c5072875367';
$url = "/api/1.0/workflow/cases/$caseId/variable";
$oRet = pmRestRequest("PUT", $url, $aVars, $oToken->access_token);
if ($oRet->status == 200) {
   print "Case variables sent.";
}

Get Case Variable: GET /case/{app_uid}/{del_index}/variable/{var_name}

Get the value of a specified variable from a case. Note that the variable must be one of the variables found in the variables list, and can't be defined in a trigger or by submitting a DynaForm control which is not associated with a variable. If needing to get the value of one of these other types of variables, then use the GET /cases/{app_uid}/variables endpoint.

GET /api/1.0/{workspace}/case/{app_uid}/{del_index}/variable/{var_name}

Note: This endpoint can return the variable from any case, regardless of its status, so it can get the variables for paused, completed or even canceled cases. The only cases for which it can't get the variables are deleted cases, because their records has been removed from the APPLICATION table in the database.

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientName
app_uidCase's unique ID./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientName
del_indexCase's delegation index, which can be obtained from the @%INDEX system variable./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientName
var_nameName of the case variable./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientName

Result:

If successful, then returns a HTTP status code of 200 (OK) and returns a object which contains the value of the variable and its label. The format depends on type of variable and its associated control.

Textboxes and textareas:
The value of the variable and its label are the same. Textareas may contain \\n (new lines).

{
  "clientName":       "Mary Rowe",
  "clientName_label": "Mary Rowe"
}

Note: Textboxes which have integer or float values are stored as strings, so it may be necessary to convert their values to numbers if doing mathematical operations.

Datetimes:
The value of the datetime will be in the format "YYYY-MM-DD HH:MM:SS" format. The label of the datetime will be in the format specified by the control's format property. Note that the time is the value that was entered by the user and doesn't adjust for time zones.

{
   "contractDate":       "2016-05-22 04:00:00",
   "contractDate_label": "05/22/2016"
}

Datetimes in version 3.0.1.7+ Enterprise Edition:
The Enterprise Edition in version 3.0.1.7 and later has Multi Time Zone Support, so datetime variables store their values in UTC time, so they aren't in the user's time zone, however, the label will be in the time zone of the user who originally entered the datetime (which may be different from the time zone of the REST user). The value of datetimes are in the YYYY-MM-DDTHH:MM:SS+HH:MM format, where +HH:MM is always set to +00:00 and can be ignored.

{
   "contractDate":       "2016-05-22T04:00:00+00:00",
   "contractDate_label": "05/22/2016 07:00"
}

Dropdown boxes, Suggest boxes and Radio buttons:
The variable holds the value of the selected option and its label holds the displayed text of the selected option.

{
   "selectCountry":       "AD",
   "selectCountry_label": "Andorra"
}

Checkboxes:
Marked checkboxes have a value of ["1"], which is the string "1" inside an array, and a default label of "true", but the label can be customized in its options property. Unmarked checkboxes have a value of ["0"], and a default label of "false".

{
   "hasContract":       ["1"],
   "hasContract_label": "true"
}

Checkgroups:
The variable for checkgroups holds an array of the values of the selected options in the checkgroup. The label variable holds a JSON string of an array of the displayed text of the selected options. Functions such as JSON.parse() in JavaScript or json_decode() in PHP can be used convert the JSON string into an array.

{
   "services":       ["accounting", "cleaning", "catering"],
   "services_label": "[\"Accounting\",\"Cleaning\",\"Catering\"]"
}

Files:
The variable for file controls is a JSON string which holds an array of the unique IDs for the case files (AppDocuments). The label is a JSON which holds an array of the filenames of the case files. Users can only select one file at a time to upload in a File control, but if that file control is found in multiple DynaForms or the same DynaForm is opened and submitted multiple times or files are uploaded to an Input Document step, then there may be multiple files in the array.

{
  "receiptFile":       "[\"32030312057351f4d3ae361014376815\"]",
  "receiptFile_label": "[\"Fixed_precision_grid_math-1.pmx\"]"
}

Grids:
The variable for grids is an object of objects, where the first row is named "1", the second row is named "2", etc. Each row object holds the values and the labels of the fields inside the row. These are named according to the IDs of the fields. Their values and labels are similar to normal variables, but checkboxes inside grids have a value of "1" or "0", not ["1"] or ["0"] like a normal checkbox outside a grid.

{
  "clientList": {
    "1": {
      "name":                "E-Z Accounting",
      "name_label":          "E-Z Accounting",
      "address":             "8473 W. 11th St.\\nHaverford, CT 284745",
      "address_label":       "8473 W. 11th St.\\nHaverford, CT 284745",
      "hasContract":         "1",
      "currentClient_label": "true",
      "contractDate_label":  "2016-05-23",
      "contractDate":        "2016-05-23 04:00:00"
    }
    "2": {
      "name":                "Cater-Rite Food Service",
      "name_label":          "Cater-Rite Food Service",
      "address":             "284 E. Seminary St.\\nSilverado, CO 28471",
      "address_label":       "284 E. Seminary St.\\nSilverado, CO 28471",
      "hasContract":         "0",
      "currentClient_label": "false",
      "contractDate_label":  "2015-12-31",
      "contractDate":        "2015-12-31 21:00:00"
    }
  }
}    

Note: Grids and the results of database queries are stored as an associative array of associative arrays in ProcessMaker, but they are converted into an object of objects, because JSON doesn't support associative arrays.

When reading this object of objects in PHP, it is recommended to either use json_decode($json, true) to convert the return object into an associative array or get_object_vars() to convert the rows in a grid to an associative array. See the example at GET /cases/{app_uid}/variables.

If an error occurs, the HTTP status code will be 300 or greater and an error object like the following might be returned:

{
   "error": {
      "code":    400,
      "message": "Bad Request: var_name: clientName does not exist"
   }
}

PHP Example:

This example gets the "receiptFile" file variable and uses json_decode() to convert from JSON strings to arrays. Then, it prints out the unique IDs and filenames in the variable.

$varName = 'receiptFile';
$caseId = '40297019257350533ba5d20087799226';
$delIndex = 1;
$url = "/api/1.0/workflow/case/$caseId/$delIndex/variable/$varName";
 
$oRet = pmRestRequest("GET", $url);
print "<pre>"; //if in a web page
var_dump($oRet);
if ($oRet->status == 200) {
   $aResponse = get_object_vars($oRet->response);
   $aFiles = json_decode($aResponse[$varName]);
   $aFilenames = json_decode($aResponse[$varName . '_label']);
   print "Files in $varName\n";
   for ($i = 0; $i < count($aFiles); $i++) {
      print "  {$aFilenames[$i]} ({$aFiles[$i]})\n";
   }
}

Get Page of Grid Variable: GET /case/{app_uid}/{del_index}/variable/{var_name}/paged

Get a page of a grid variable of a case. Note that the variable must be one of the variables found in the variables list, and can't be defined in a trigger or by submitting a DynaForm control which is not associated with a variable. If needing to get the value of one of these other types of variables, then use the GET /cases/{app_uid}/variables endpoint.

GET /api/1.0/{workspace}/case/{app_uid}/{del_index}/variable/{var_name}/paged

Note: This endpoint can return the variable from any case, regardless of its status, so it can get the variables for paused, completed or even canceled cases. The only cases for which it can't get the variables are deleted cases, because their records has been removed from the APPLICATION table in the database.

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged
app_uidCase's unique ID./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged
del_indexCase's delegation index, which can be obtained from the @%INDEX system variable./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged
var_nameName of the case variable./api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged

Optional URL Parameters:

ParameterDescriptionExample
filterA case-insensitive search in grid fields. Only rows whose fields contain the filter string are returned..../paged?filter=catering
lfilterA case-insensitive search in the beginning of grid fields. Only rows whose fields start with the filter string are returned..../paged?lfilter=e-z
rfilterA case-insensitive search in the end of grid fields. Only rows whose fields end with the filter string are returned..../paged?rfilter=23484
startThe number of row in the grid where the list begins. 0 is the first row, 1 begins with the second row, etc. If combined with a filter, then only rows whose fields contain the filter string are returned..../paged?start=10&limit=5
limitThe number of rows in the grid which are returned..../paged?start=10&limit=5

Result:

If successful, then returns a HTTP status code of 200 (OK) and returns a page object. Remember that checkboxes inside grids have a value of "1" or "0", not ["1"] or ["0"] like a normal checkbox outside a grid.

{
  "total":  2,
  "start":  0,
  "limit":  0,
  "filter": "",
  "data": {
    "1": {
      "name":               "EZ-Catering",
      "name_label":         "EZ-Catering",
      "address":            "234 W. 11th St.\r\nBloomington IN 23484",
      "address_label":      "234 W. 11th St.\r\nBloomington IN 23484",
      "contractDate_label": "2016-05-31",
      "contractDate":       "2016-05-31 00:00:00",
      "currentClient":      "1",
      "currentClient_label":"true"
    }
    "2": {
      "name":               "Smithee Lawn Service",
      "name_label":         "Smithee Lawn Service",
      "address":            "555 Main St.\r\nEvansville IN 46234",
      "address_label":      "555 Main St.\r\nEvansville IN 46234",
      "contractDate_label": "2016-05-08",
      "contractDate":       "2016-05-08 00:00:00",
      "currentClient":      "0",
      "currentClient_label":"false"
    }
  }
}  

Note: Grids and the results of database queries are stored as an associative array of associative arrays in ProcessMaker, but they are converted into an object of objects, because JSON doesn't support associative arrays.

When reading this object of objects in PHP, it is recommended to either use json_decode($json, true) to convert the return object into an associative array or get_object_vars() to convert the rows in a grid to an associative array. See the example at GET /cases/{app_uid}/variables.

If an error occurs, the HTTP status code will be 300 or greater and an error object like the following is returned for 400 and 404 errors:

{
   "error": {
      "code":    400,
      "message": "Bad Request: var_name: clientName does not exist"
   }
}

PHP Example:

This example prints out the contents of the "clientList" grid in an HTML table.

$varName = 'clientList';
$caseId =  '40297019257350533ba5d20087799226';
$delIndex = 1;
$url = "/api/1.0/workflow/case/$caseId/$delIndex/variable/$varName/paged";
 
$oRet = pmRestRequest("GET", $url);
if ($oRet->status == 200 and $oRet->response->total > 0) {
   $aRows = get_object_vars($oRet->response->data);
   print '<style type="text/css">' .
      'table.myTable {border-collapse: collapse;}' .
      'table.myTable td, table.myTable th ' .
      '{border: 1px solid green; padding: 5px;}</style> ' .
      '<table class="myTable">' . "\n<tr>";
   foreach ($aRows["1"] as $fieldId => $val) {
      print "<th>$fieldId</th>";
   }
   print "</tr>\n";
             
   foreach ($aRows as $oRow) {
      $aRow = get_object_vars($oRow);
      print "<tr>";
      foreach ($aRow as $fieldId => $val){
         print "<td>$val</td>";
      }
      print "</tr>\n";
   }
   print "</table>\n";
}

The above code produces the following web page:

namename_labeladdressaddress_labelcontractDate_labelcontractDatecurrentClientcurrentClient_label
EZ-CateringEZ-Catering234 W. 11th St. Bloomington IN 23484234 W. 11th St. Bloomington IN 234842016-05-312016-05-31 00:00:001true
Smithee Lawn ServiceSmithee Lawn Service555 Main St. Evansville IN 46234555 Main St. Evansville IN 462342016-05-082016-05-08 00:00:000false
Best Accounting ServicesBest Accounting Services4332 Oak St. Putnamville, IN 462344332 Oak St. Putnamville, IN 462342016-05-162016-05-16 00:00:001true

Create Variable: POST /cases/{app_uid}/{del_index}/variable/{var_name}

Available in version 3.0.1.8 and later.

Create a variable in a case, meaning the variable is instantiated in the case.

POST /api/1.0/{workspace}/cases/{app_uid}/{del_index}/variable/{var_name}

Note: The variable must be one of the existing variables found in the variables list, but cannot yet be instantiated in the case. A variable is normally instantiated in a case when a DynaForm control associated with that variable is submitted or when variables are passed to a new case created with the POST /cases or POST /cases/impersonate endpoints. If needing to create a variable which isn't in the variable list, see the PUT /cases/{app_uid}/variables endpoint.

Warning: This endpoint currently has a bug, which allows it to create variables in cases which have COMPLETED, PAUSED or CANCELLED status.

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow".http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
app_uidCase's unique ID.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
del_indexCase's delegation index, which can be obtained from the @%INDEX system variable.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
var_nameName of the case variable.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName

POST Parameters:

All variables except for grid variables are set in the following manner:

{ "variable": value, "variable_label": label }

For the format of variables associated with different types of DynaForm controls, see Get Case Variable above. The value can be any data type, except NULL which will cause an error. If the value is a number, it will be converted to a string. Values of true will be converted to "1" and false will be converted to "0". Objects will be converted into associative arrays when stored in ProcessMaker. variable_label must be included to avoid an error, even if setting a variable which isn't associated with a DynaForm control.

Note: It is possible to create File variables, but they will only be used by ProcessMaker if they have corresponding records in the APP_DOCUMENT table in the database. See: Upload Input Document: POST /cases/{app_uid}/input-document

Grids variables are instantiated with the following format:

{ "1": { "field1Id": value, "field1Id_label": label, "field2Id": value, "field2Id_label": label, ... }, "2": { "field1Id": value, "field1Id_label": label, "field2Id": value, "field2Id_label": label, ... }, ... }

The rows of the grid, start their numbering from "1". The IDs of fields are case sensitive and must be spelled exactly as defined in the DynaForm Designer. Each row must have at least one field in it, or the row will not be added. If a field is included in a row, it must also include its label or an error will occur. It is not possible to include additional fields which aren't defined in the grid in the DynaForm designer.

Checkboxes inside grids have a value of "1" or "0", not ["1"] or ["0"] like a normal checkboxes outside a grid.

The grid variable must be associated with grid control in a DynaForm. If needing to pass the contents of a grid to an unassociated variable, then pass it to an array variable.

Result:

If the variable was instantiated, then the endpoint returns a HTTP status code of 201 (Created) and returns an object with the value and label of the variable. If a grid variable, then the contents of the grid are returned in an object, but there is no label.

If the variable has already been instantiated in the case, then the endpoint returns the following error object:

{
   "error": {
      "code": 400,
      "message": "Bad Request: The Variable with var_name: \"clientName\" already exists in Case"
   }
}

If the variable doesn't exist in the process' variable list, then the endpoint returns the following error object:

{
   "error": {
      "code": 400,
      "message": "Bad Request: var_name: clientName does not exist"
   }
}

If the field ID is misspelled or doesn't exist in the second row in a grid, then the endpoint returns the following error object:

{
   "error": {
      "code": 400,
      "message": "Bad Request: 2: Field Invalid (clientName)"
   }
}

Examples:

1. Instantiate a string variable associated with a textbox.

Request:

POST http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName

{
  "clientName":       "Brooklyn Brickworks, Inc.",
  "clientName_label": "Brooklyn Brickworks, Inc."
}

Response:

201 (Created)
{
  "clientName":       "Brooklyn Brickworks, Inc.",
  "clientName_label": "Brooklyn Brickworks, Inc."
}

2. Instantiate a grid variable.

Request:

POST http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName

{
  "1": {
    "name":               "EZ-Catering",
    "name_label":         "EZ-Catering",
    "address":            "234 W. 11th St.\r\nBloomington IN 23484",
    "address_label":      "234 W. 11th St.\r\nBloomington IN 23484",
    "contractDate_label": "2016-05-31",
    "contractDate":       "2016-05-31 00:00:00",
    "currentClient":      "1",
    "currentClient_label":"true"
  },
  "2": {
    "name":               "Smithee Lawn Service",
    "name_label":         "Smithee Lawn Service",
    "address":            "555 Main St.\r\nEvansville IN 46234",
    "address_label":      "555 Main St.\r\nEvansville IN 46234",
    "contractDate_label": "2016-05-08",
    "contractDate":       "2016-05-08 00:00:00",
    "currentClient":      "0",
    "currentClient_label":"false"
  }
}  

Response:

201 (Created)
{
  "1": {
    "name":               "EZ-Catering",
    "name_label":         "EZ-Catering",
    "address":            "234 W. 11th St.\r\nBloomington IN 23484",
    "address_label":      "234 W. 11th St.\r\nBloomington IN 23484",
    "contractDate_label": "2016-05-31",
    "contractDate":       "2016-05-31 00:00:00",
    "currentClient":      "1",
    "currentClient_label":"true"
  },
  "2": {
    "name":               "Smithee Lawn Service",
    "name_label":         "Smithee Lawn Service",
    "address":            "555 Main St.\r\nEvansville IN 46234",
    "address_label":      "555 Main St.\r\nEvansville IN 46234",
    "contractDate_label": "2016-05-08",
    "contractDate":       "2016-05-08 00:00:00",
    "currentClient":      "0",
    "currentClient_label":"false"
  }
}

PHP Examples:

1.This example instantiates a dropdown box associated with string variable named "documentType".

$varName = 'documentType';
$caseId =  '40297019257350533ba5d20087799226';
$delIndex = 1;
$url = "/api/1.0/workflow/case/$caseId/$delIndex/variable/$varName";
$aParams = array(
   $varName          => 'copy',
   $varName.'_label' => 'Printed Copy'
);
 
$oRet = pmRestRequest("POST", $url, $aParams);
if ($oRet->status == 201) {
   print "Variable $varName created.\n";
}

2. This example instantiates a grid variable. Notice how \r\n is used to create line breaks in the "address" textarea.

$varName = 'clientList';
$caseId =  '40297019257350533ba5d20087799226';
$delIndex = 1;
$url = "/api/1.0/workflow/case/$caseId/$delIndex/variable/$varName";
$aParams = array(
  "1"=> array(
    "name"=>               "EZ-Catering",
    "name_label"=>         "EZ-Catering",
    "address"=>            "234 W. 11th St.\r\nBloomington IN 23484",
    "address_label"=>      "234 W. 11th St.\r\nBloomington IN 23484",
    "contractDate_label"=> "2016-05-31",
    "contractDate"=>       "2016-05-31 00:00:00",
    "currentClient"=>      "1",
    "currentClient_label"=>"true"
  ),
  "2"=> array(
    "name"=>               "Smithee Lawn Service",
    "name_label"=>         "Smithee Lawn Service",
    "address"=>            "555 Main St.\r\nEvansville IN 46234",
    "address_label"=>      "555 Main St.\r\nEvansville IN 46234",
    "contractDate_label"=> "2016-05-08",
    "contractDate"=>       "2016-05-08 00:00:00",
    "currentClient"=>      "0",
    "currentClient_label"=>"false"
  )
);

$oRet = pmRestRequest("POST", $url, $aParams);
if ($oRet->status == 201) {
   print "Grid $varName created.\n";
}

Update Variable: PUT /cases/{app_uid}/{del_index}/variable/{var_name}

Available in version 3.0.1.8 and later.

Update the value of a variable in a case. The variable must already be instantiated in the case, in order to update its value.

PUT /api/1.0/{workspace}/cases/{app_uid}/{del_index}/variable/{var_name}

Note: The variable must be one of the existing variables found in the process' variables list and it has to already be instantiated in the case. A variable is normally instantiated in a case when a DynaForm control associated with that variable is submitted or when variables are passed to a new case created with the POST /cases or POST /cases/impersonate endpoints. If needing to create a variable which isn't in the variable list, see the PUT /cases/{app_uid}/variables endpoint.

Warning: This endpoint currently has a bug, which allows it to update variables in cases which have COMPLETED, PAUSED or CANCELLED status.

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow".http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
app_uidCase's unique ID.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
del_indexCase's delegation index, which can be obtained from the @%INDEX system variable.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
var_nameName of the case variable.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName

POST Parameters:

The format to update variables is the same as creating them. See: Create Variable: POST /cases/{app_uid}/{del_index}/variable/{var_name}

Result:

If the variable was updated, then the endpoint an HTTP status code of 204 (No content), which indicates that the request was processed correctly and there is no response.

If the variable has not been instantiated in the case, then the endpoint returns the following error object:

{
   "error": {
      "code": 400,
      "message": "Bad Request: The Variable with var_name: \"clientName\" does not exist in Case"
   }
}

Examples:

1. Update a datetime variable which uses the format MM/DD/YYYY hA in its label.

Request:

PUT http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/dueDate

{
  "dueDate":       "2016-03-25 18:00:00",
  "dueDate_label": "03/25/2006 6PM"
}

Response:

204 (No content)

2. Update a grid variable.

Request:

PUT http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName

{
  "1": {
    "name":               "EZ-Catering",
    "name_label":         "EZ-Catering",
    "address":            "234 W. 11th St.\r\nBloomington IN 23484",
    "address_label":      "234 W. 11th St.\r\nBloomington IN 23484",
    "contractDate_label": "2016-05-31",
    "contractDate":       "2016-05-31 00:00:00",
    "currentClient":      "1",
    "currentClient_label":"true"
  },
  "2": {
    "name":               "Smithee Lawn Service",
    "name_label":         "Smithee Lawn Service",
    "address":            "555 Main St.\r\nEvansville IN 46234",
    "address_label":      "555 Main St.\r\nEvansville IN 46234",
    "contractDate_label": "2016-05-08",
    "contractDate":       "2016-05-08 00:00:00",
    "currentClient":      "0",
    "currentClient_label":"false"
  }
}  

Response:

204 (No content)

PHP Example:

This example instantiates a variable for a checkgroup.

$varName = 'services';
$caseId =  '40297019257350533ba5d20087799226';
$delIndex = 1;
$url = "/api/1.0/workflow/case/$caseId/$delIndex/variable/$varName";
$aParams = array(
   $varName          => array("legal", "consulting", "marketing"),
   $varName.'_label' => json_encode(array("Legal Services", "Consulting", "Marketing"))
);
 
$oRet = pmRestRequest("PUT", $url, $aParams);
if ($oRet->status == 204) {
   print "Variable $varName updated.\n";
}

Delete Variable: DELETE /cases/{app_uid}/{del_index}/variable/{var_name}

Available in version 3.0.1.8 and later.

Delete a variable in a case.

PUT /api/1.0/{workspace}/cases/{app_uid}/{del_index}/variable/{var_name}

Note: The variable must be one of the existing variables found in the process' variables list and it has to already be instantiated in the case.

Warning: This endpoint currently has a bug, which allows it to update variables in cases which have COMPLETED, PAUSED or CANCELLED status.

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow".http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
app_uidCase's unique ID.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
del_indexCase's delegation index, which can be obtained from the @%INDEX system variable.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
var_nameName of the case variable.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName

Optional URL Parameters:

ParameterDescriptionExample
?keys=XDelete a specified row in a grid, where the first row is 1, the second is 2, etc.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientList?keys=2
?keys=X,Y,...Delete specified rows in a grid, where X,Y,... are the row index numbers. The first row is 1, the second is 2, etc.http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientList?keys=2,5,11

Result:

If the variable was deleted, then the HTTP status code is 200 (OK), and there is no response.

If the variable has not been instantiated in the case or it doesn't exist in its process' variable list, then the HTTP status code is set to 404 (Not found) and the response is following error object:

{
   "error": {
      "code": 404,
      "message": "Not Found"
   }
}

This same error object is returned when trying to delete a row index number which doesn't exist.

Examples:

1. Update a variable.

Request:

DELETE http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/dueDate

Response:

200 (OK)

2. Delete the first and third rows in a grid variable.

Request:

DELETE http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientList?keys=1,3

Response:

200 (OK)

PHP Example:

This example deletes a variable.

$varName = 'services';
$caseId =  '40297019257350533ba5d20087799226';
$delIndex = 1;
$url = "/api/1.0/workflow/case/$caseId/$delIndex/variable/$varName";
 
$oRet = pmRestRequest("DELETE", $url);
if ($oRet->status == 200) {
   print "Variable $varName deleted.\n";
}

Input Documents

The following endpoints are used to control Input Document files uploaded to cases:

  1. Get a list of Input Documents for case: GET /cases/{app_uid}/input-documents
  2. Get an Input Document information: GET /cases/{app_uid}/input-document/{app_doc_uid}
  3. Upload Input Document: POST /cases/{app_uid}/input-document
  4. Download an Input Document: GET /cases/{app_uid}/input-document/{app_doc_uid}/file?v={app_doc_version}
  5. Remove an Input Document file: DELETE /cases/{app_uid}/input-document/{app_doc_uid}

Get a list of Input Documents: GET /cases/{app_uid}/input-documents

Returns a list of the uploaded Input Document files for a given case. If versioning is enabled, it only returns the most recent versions of Input Document files. Note that only Input Document files are returned when the logged in user has one of the following rights to view the files:

  • The Input Document is a step in the current task of the case and the logged-in user is currently assigned to work on the case.
  • The logged in user has process permissions to view the task where the Input Document is a step.

Note that it is possible to still get the list of Input Documents for a case, regardless of the case's status, so it is possible to get the Input Document files for cases which have been paused, canceled or completed if the user has process permissions.

Note that this endpoint does NOT return Input Document files when the logged-in user is assigned as Process Supervisor to the Input Document, so the user will have to be given Process Permissions (This issue is fixed from version 3.0.1.5).

GET /api/1.0/{workspace}/cases/{app_uid}/input-documents

URL Parameters:

ParameterDescriptionExample
workspaceWorkspace name which by default is "workflow"./api/1.0/workflow/cases/37213410154d375de3e3620044382558/input-documents
app_uidCase's unique ID./api/1.0/workflow/cases/37213410154d375de3e3620044382558/input-documents

Result:

If successful, the HTTP status is set is 200 and array of objects is returned with information about each uploaded Input Document file:

[Start array of file objects.
{Start first file object.
"app_doc_uid",Unique ID of Input Document file.
"app_doc_filename",Filename of Input Document file
"doc_uid", Unique ID of the Input Document definition.
"app_doc_version", Version of the uploaded file, with counts starting from "1". If versioning isn't enabled, then this value is always "1".
"app_doc_create_date", Datetime in "YYYY-MM-DD HH:MM:SS" format when file was uploaded.
"app_doc_create_user", User who uploaded file to the case in "last-name, first-name (username)" format.
"app_doc_type", Type of document which can be: "INPUT", "OUTPUT" or "ATTACHED". (An "ATTACHED" file is uploaded through a DynaForm's file field which isn't associated with an Input Document).
"app_doc_index", The case document index which counts the files in the order they were uploaded/created in the case, regardless of whether they are Input Document files, Output Document files or attached to a file field in a DynaForm. The first file has an index of 1, the second has an index of 2, etc. This index also counts files which are uploaded as previous versions of Input Document files.
"app_doc_link",Relative URL to download the file at "cases/cases_ShowDocument?a={app_doc_uid}&v={app_doc_version}". To form a complete URL, prepend "https://{domain}/sys{workspace}/{lang}/{skin}/" to this relative URL. It is possible to download the file as long as the user has an active login session, which by default should last for 24 minutes, so the file can be downloaded by the same script which called this endpoint, using a download program such as cURL or wget. In PHP, functions like file() and file_get_contents() can be used to download the contents of a file from a URL. In JavaScript, the web browser can be redirected to open this URL by assigning it to window.location.href. XMLHttpRequest can be used to download the contents of the file to a variable.
},End first file object
...Any additional file objects
]End array.

For example:

[
   {
      "app_doc_uid": "8113107945330516f47ccc0076416056",                                  
      "app_doc_filename": "receipts.pdf",                                                    
      "doc_uid": "70158392952979dedd77fe0058957493",                                      
      "app_doc_version": "1",                                                            
      "app_doc_create_date": "2014-03-24 11:38:23",                                      
      "app_doc_create_user": ", Administrator (admin)",                                  
      "app_doc_type": "INPUT",                                                            
      "app_doc_del_index": 1,                                                            
      "app_doc_link": "cases/cases_ShowDocument?a=8113107945330516f47ccc0076416056&v=1"  
   },
   {
      "app_doc_uid": "412239205533051a99876b8018449052",
      "app_doc_filename": "ClientInfo.html",
      "doc_uid": "70158392952979dedd77fe0058957493",
      "app_doc_version": "1",
      "app_doc_create_date": "2014-03-24 11:39:21",
      "app_doc_create_user": "Doe, Jane (janedoe)",
      "app_doc_type": "INPUT",
      "app_doc_del_index": 2,
      "app_doc_link": "cases/cases_ShowDocument?a=412239205533051a99876b8018449052&v=1"
   }
]
Note: The logged-in user may only see information about Input Document files if he/she is currently assigned to the case or has process permissions to see the Input Document to which the files were uploaded.

PHP examples:

This example looks for an Input Document file named "client_bill.txt" and then uses the file_get_contents() function to download it. It then uses the preg_match() function to look for the first line which contains "Invoice No: XXXXXXXXXXXX" so it can extract the invoice number. Note that file_get_contents() can be used to download both text files and binary files, but preg_match() can only be used to search in text files.

$caseId = '44756102555c4e859630f43089650367';
$url = "/api/1.0/{workspace}/cases/$caseId/input-documents";
$method = "GET";
$oRet = pmRestRequest($method, $url);
if ($oRet->status == 200 and count($oRet->response) > 0) {
   //look for client_bill.txt file in array of files
   foreach ($oRet->response as $oDoc) {
      if ($oDoc->app_doc_filename == "client_bill.txt") {
         $fileUrl = 'http://myserver.com/sysworkflow/en/neoclassic/' . $oDoc->app_doc_link;
         $sFile = file_get_contents($fileUrl) or die("Unable to retrieve file '$fileUrl'");
     
         if (preg_match('/^Invoice No: ([A-Z0-9]{12})/', $sFile, $match)) {
            $invoiceNo = $match[1];
            //do something with the invoice number
         }
      }
   }
}

This example uses cURL to download all the Input Document file(s) for a case. If image files are found, then they are stored on the harddrive. Using cURL downloads both the contents of the file and its header, which can be useful if needing information from the header. The tricky part is separating the contents from the header.

$caseId = '44756102555c4e859630f43089650367';
$url = "/api/1.0/{workspace}/cases/$caseId/input-documents";
$method = "GET";
$oRet = pmRestRequest($method, $url);

if ($oRet->status == 200 and count($oRet->response) > 0) {
   set_time_limit(0);
     
   foreach($oRet->response as $oDoc) {
      $fileUrl = 'http://localhost:301/sysworkflow/en/neoclassic/' . $oDoc->app_doc_link;
     
      $resource = curl_init();
      curl_setopt($resource, CURLOPT_URL, $fileUrl);
      curl_setopt($resource, CURLOPT_HEADER, 1);
      curl_setopt($resource, CURLOPT_RETURNTRANSFER, 1);
      curl_setopt($resource, CURLOPT_BINARYTRANSFER, 1);
      $file = curl_exec($resource);
      $status = curl_getinfo($resource, CURLINFO_HTTP_CODE);
     
      if ($status != 200) {
         die("Error Status: $status\nUnable to retrieve $fileUrl");
      }
      //separate the HTTP header from the file contents:        
      $aFileParts = explode("\n\r", $file, 2);
      $header = $aFileParts[0];
      $contents = substr($aFileParts[1], 1);
     
      //create an associative array of header information:
      preg_match_all('/^([a-zA-Z\-]+): (.+)/m', $header, $aMatches, PREG_SET_ORDER);
      $aHeader = array();
      foreach ($aMatches as $aMatch) {
         $aHeader[$aMatch[1]] = trim($aMatch[2]);
      }
       
      //if an image file, then save file to harddrive:
      if (strpos($aHeader['Content-Type'], 'image') === 0) {    
         file_put_contents('/some/dir/' . $filename, $contents);
      }
   }
}

The following example first uses cURL to download the first file in the case, then it serves up that same file so the user can download the file as an attachment in the user's web browser. Depending on the configuration of the web browser, file will either be automatically downloaded to the user's local computer or a dialog box will open asking where the user wants to save the file, which gives the user the opportunity to cancel the download.

Note that nothing should be printed by the code or it will corrupt the contents of the downloaded file. It is only possible to download one file at a time with this sample code, so it is recommended to combine all the files in a ZIP file if needing to download more than one file.

$caseId = '44756102555c4e859630f43089650367';
$url = "/api/1.0/{workspace}/cases/$caseId/input-documents";
$method = "GET";
$oRet = pmRestRequest($method, $url);

if ($oRet->status == 200 and count($oRet->response) > 0) {
   set_time_limit(0);
   //get first file  
   $oDoc = $oRet->response[0];
   $fileUrl = 'http://localhost:301/sysworkflow/en/neoclassic/' . $oDoc->app_doc_link;
   $resource = curl_init();
   curl_setopt($resource, CURLOPT_URL, $fileUrl);
   curl_setopt($resource, CURLOPT_HEADER, 1);
   curl_setopt($resource, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($resource, CURLOPT_BINARYTRANSFER, 1);
   $file = curl_exec($resource);
   $status = curl_getinfo($resource, CURLINFO_HTTP_CODE);
     
   if ($status != 200) {
      die("Error Status: $status\nUnable to retrieve $fileUrl");
   }
   //separate the HTTP header from the file contents:        
   $aFileParts = explode("\n\r", $file, 2);
   $header = $aFileParts[0];
   $contents = substr($aFileParts[1], 1);
     
   //create an associative array of header information:
   preg_match_all('/^([a-zA-Z\-]+): (.+)/m', $header, $aMatches, PREG_SET_ORDER);
   $aHeader = array();
   foreach ($aMatches as $aMatch) {
      $aHeader[$aMatch[1]] = trim($aMatch[2]);
   }
   //serve up file to be downloaded in web browser:    
   header('Cache-Control: no-store, no-cache, must-revalidate');
   header('Content-Disposition: ' . $aHeader['Content-Disposition']);
   header('Content-Length: '      . $aHeader['Content-Length']);
   header('Content-Type: '        . $aHeader['Content-Type']);    
   echo $contents;
   ob_flush();
   flush();
}

Get Input Document Information: GET /cases/{app_uid}/input-document/{app_doc_uid}

Return the detailes of an uploaded document for a given case.

GET /api/1.0/{workspace}/cases/{app_uid}/input-document/{app_doc_uid}

Parameters:

NameTypeDescription
workspaceStringWorkspace name
app_uidStringCase unique ID
app_doc_uidStringInput Document file's unique ID, which

Result:

Returns an object with the same information about the specified Input Document file which is returned by GET /cases/{app_uid}/input-documents. For example:

{                                                                                
   "app_doc_uid": "8113107945330516f47ccc0076416056",                            
   "app_doc_filename": "ProductionQuota.docx",                                  
   "doc_uid": "70158392952979dedd77fe0058957493",              
   "app_doc_version": "1",                                      
   "app_doc_create_date": "2014-03-24 11:38:23",                      
   "app_doc_create_user": "Doe, John (johndoe)",                  
   "app_doc_type": "INPUT",
   "app_doc_index": 1,                                                              
   "app_doc_link": "cases/cases_ShowDocument?a=8113107945330516f47ccc0076416056&v=1"
}

Upload Input Document: POST /cases/{app_uid}/input-document

Uploads a new Input Document file to a specified case. Note that the logged-in user must either be currently assigned to work on the case or a Process Supervisor with permissions to access the Input Document; otherwise, this endpoint returns an HTTP status code of 302.

POST /api/1.0/{workspace}/cases/{app_uid}/input-document

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
app_uidStringCase UID

POST Fields:

NameTypeDescription
inp_doc_uidStringThe unique ID of the Input Document definition.
tas_uidStringThe unique ID of the task where the Input Document is a step.
app_doc_commentStringA comment in plain text about the uploaded file.
formStringThe path to the file to upload to the ProcessMaker server. This path cannot be a web URL. If needing to use a file located on the internet, first download the file and save it as a local file to be uploaded.
If using PHP, be sure to place "@" before the path to include the file. If @ is not used, the status code will be 400 with the message "Bad Request: This filename does not exist!". If using PHP 5.5 or later, a new security feature has been added to prevent code injection attacks, so use a CurlFile object instead of @. See the code example below which uses phpversion() to check the PHP version before instantiating CurlFile(). The uploaded file will have the same filename. To rename the file, move it to a new file location before uploading it to this REST endpoint.

Result:

If the file was successfully uploaded, it returns an HTTP status code of 200 and a response object with information about the new Input Document file, such as:

{
   "app_doc_uid":         "43019952255dfa40100e0b7048036445",
   "app_doc_filename":    "companyVideo.ogv",
   "doc_uid":             "30967501355df8ce0132ac7027392886",
   "app_doc_version":     "1",
   "app_doc_create_date": "2015-08-27 19:57:52",
   "app_doc_create_user": "Doe, Bob (bob)",
   "app_doc_type":        "INPUT",
   "app_doc_index":       "3",
   "app_doc_link":        "cases/cases_ShowDocument?a=43019952255dfa40100e0b7048036445&v=1"
}
If an error occurs, an HTTP status code of 300 or greater is returned with a message object such as:
{
   "error":  {
      "code":    413,
      "message": "Request Entity Too Large: Uploaded file (companyVideo.ogv) is too big."
    }
}

Note: If using PHP, in order to send POST fields to REST endpoints which contain objects or arrays, the POST fields have to be encoded with the http_build_query() function. However, passing the filename through the http_build_query() function mangles it and this endpoint will return a status code of 400 and the message "Bad Request: This filename does not exist!". Either make a pmRestRequest() function which doesn't use the http_build_query() function or use code like the example below to upload the file.

Note: If the uploaded file is larger than the upload_max_filesize setting in the php.ini file on the ProcessMaker server, then the HTTP status code will be 413 with the error message "Request Entity Too Large: Uploaded file (filename) is too big.". If the uploaded file is larger than the post_max_size setting in the php.ini file on the ProcessMaker server, then the endpoint will return a status code and the message "Bad Request: `tas_uid` is required but missing".

Note: It is not possible to send a file to the POST cases/{app_uid}/input-document endpoint using JavaScript, because the JavaScript language is not designed to handle file uploads. If using JavaScript, then some server-side code will need to be added to handle file uploads. See the PHP code examples below.

PHP Example 1:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "bob", "p4sSw0rd");
   
$inputDocId = '30967501355df8ce0132ac7027392886';
$taskId     = '39558947555df747738bc05034476159';
$caseId     = '46509787255df8bc70f2f17099023224';
$url        = 'http://'. $_SERVER['SERVER_NAME'] .':'. $_SERVER['SERVER_PORT'] . "/api/1.0/workflow/cases/$caseId/input-document";
$path     = '/home/user/companyVideo.ogv';
   
$aVars = array(
   'inp_doc_uid'     => $inputDocId,
   'tas_uid'         => $taskId,
   'app_doc_comment' => 'Promotional video for clients',
   'form'            => (phpversion() >= "5.5") ? new CurlFile($path) : '@' . $path
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer ' . $oToken->access_token));
curl_setopt($ch, CURLOPT_POSTFIELDS, $aVars);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$oResponse = json_decode(curl_exec($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
 
if ($httpStatus == 200) {
    $caseFileId = $oResponse->app_doc_uid;
}  
elseif (is_object($oResponse) and isset($oResponse->error)) {
   print "Error code: {$oResponse->error->code}\n" .
         "Message: {$oResponse->error->message}\n";
}
else {
   print "Error code: $httpStatus";
}

PHP Example 2:

The following HTML form contains a file input field named "receipts[]" which allows multiple files to be selected and uploaded at the same time:

<html>
<form action="processFiles.php" enctype="multipart/form-data" method="post">
<p>
Select receipt file(s) to upload:<br>
<input type="file" name="receipts[]" id="receipts[]" multiple="multiple" size="40">
</p>
<p>
<input type="submit" value="Send">
</p>
</form>
</html>

When file(s) are selected and the above form is submitted, the $_FILES superglobal in PHP will contain information about the files which were uploaded to the "receipts[]" file field. For example, if two files were uploaded named "officeExpenses.jpg" and "inventoryList.xls", then $_FILES might contain:

$_FILES = array(
  "receipts" => array(
    "name" => array(
      "officeExpenses.jpg",
      "inventoryList.xls"
    ),
    "type" => array(
      "image/jpeg",
      "application/excel"
    ),
    "tmp_name" => array(
      "/tmp/phpuYgFXM",
      "/tmp/phpbiwPUZ"
    ),
    "error" => array(
      0,
      0
    ),
    "size" => array(
      11016,
      8962
    )
  )
);

In the same directory, the following processFiles.php file takes the files which were uploaded and sends them to the POST cases/{app_uid}/input-document endpoint:

$oToken = pmRestLogin("IAIERTORPBHIJZXEPNSUANXLKYPKODJU", "71308091055cb7094026089092397336", "bob", "p4sSw0rd");
if (empty($oToken) or isset($oToken->error))  
  die("Error " . $oToken->error->code .': '. $oToken->error->message);

$inputDocId = '30967501355df8ce0132ac7027392886';
$taskId     = '39558947555df747738bc05034476159';
$caseId     = '46509787255df8bc70f2f17099023224';
$url        = 'http://'. $_SERVER['SERVER_NAME'] .':'. $_SERVER['SERVER_PORT'] . "/api/1.0/workflow/cases/$caseId/input-document";
$nFiles = count($_FILES['receipts']['name']);

for ($i = 0; $i < $nFiles; $i++) {
   $path = $_FILES['receipts']['tmp_name'][$i];
   $type = $_FILES['receipts']['type'][$i];
   $filename = $_FILES['receipts']['name'][$i];
   //rename file from temp name to real name:
   rename($path, sys_get_temp_dir() .'/'. $filename); //reverse \ for windows systems
 
   $aVars = array(
      'inp_doc_uid'     => $inputDocId,
      'tas_uid'         => $taskId,
      'app_doc_comment' => '',
      'form'            => (phpversion() >= "5.5") ? new CurlFile($path, $type) : '@'.$path
   );

   $ch = curl_init();
   curl_setopt($ch, CURLOPT_URL, $url);
   curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer ' . $oToken->access_token));
   curl_setopt($ch, CURLOPT_POSTFIELDS, $aVars);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   $oResponse = json_decode(curl_exec($ch));
   $httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
   curl_close($ch);
   unlink(sys_get_temp_dir() .'/'. $filename); //delete file
}

Download an Input Document: GET /cases/{app_uid}/input-document/{app_doc_uid}/file?v={version}

Download an uploaded document for a given case.

GET /api/1.0/{workspace}/cases/{app_uid}/input-document/{app_doc_uid}/file?v={app_doc_version}

Parameters:

NameTypeDescription
workspaceStringWorkspace name.
app_uidStringCase unique ID.
app_doc_uidStringInput Document file's unique ID.
app_doc_versionInteger(Optional)Version of the document, with counts starting from "1". If not included, the last version of the document will be downloaded.

Result:

If the file is successfully download, 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 greater and an error object is returned, such as:

{
    "error": {
        "code": 400,
        "message": "Bad Request: Error loading Document 30441284158458441472297061707703/3. This row doesn't exist!"
    }
}

PHP example:
Download the uploaded input document file into the specified path.

$output_filename = "/opt/Receipt_1.png"; //Path where to download the document and name of the file
$host = "http://localhost/api/1.0/workflow/cases/8814697265845840e4a5452044453554/input-document/30441284158458441472297061707703/file?v=1";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $host);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer 3904087b7b9a2bd192eb07babefcbfd9d06b2b19' ));
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_AUTOREFERER, false);
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_HEADER, 0);
$result = curl_exec($ch);
curl_close($ch);

$fp = fopen($output_filename, 'w');
fwrite($fp, $result);
fclose($fp);

Delete Input Document: DELETE /cases/{app_uid}/{del_index}/input-document/{app_doc_uid}

Remove an Input Document file from a given case.

DELETE /api/1.0/{workspace}/cases/{app_uid}/{del_index}/input-document/{app_doc_uid}

Note: This endpoint does not delete the record of the Input Document file from the database, nor delete its file on the server's harddrive, stored at {install-directory}/shared/sites/{workspace}/files/XXX/XXX/XXX/XXXXXXXXXXXXXXXXXXXXXXX/{app_doc_uid}_{version}.{extension}, where XXX... is the app_uid (case ID). All it does change the value of the wf_{workspace}.APP_DOCUMENT.APP_DOC_STATUS field in the database from "ACTIVE" to "DELETED" so the file will not appear in the ProcessMaker interface. Therefore, the deletion of the file can be undone by updating the database record to change the status back to "ACTIVE".

URL Parameters:

NameTypeDescription
workspaceStringWorkspace name
app_uidStringCase UID
app_doc_uidStringDocument UID

Result:

If the file was successfully removed, 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 greater and an error object is returned, such as:

 
{
   "error": {
      "code": 400,
      "message": "Bad Request: This input document with inp_doc_uid: 97205510555e4a28a092857090745482 does not exist!"
   }
}

PHP example:

$caseId     = '44756102555c4e859630f43089650367';
$caseFileId = '97205510555e4a28a092857090745482';
$url = "/api/1.0/{workspace}/cases/$caseId/input-document/$caseFileId";
$oRet = pmRestRequest("DELETE", $url);

if ($oRet->status == 200) {
   print "Input Document file deleted.\n";
}

Output Documents

The following endpoints are used to access and control generated Output Documents:

  1. Get the generated Output Documents for a case: GET /cases/{app_uid}/output-documents
  2. Get one generated Output Document: GET /cases/{app_uid}/output-document/{app_doc_uid}
  3. Generate an Output Document for a case: POST /cases/{app_uid}/{del_index}/output-document/{out_doc_uid}
  4. Removes a generated Output Document from a case: DELETE /cases/{app_uid}/output-document/{app_doc_uid}

Get Output Documents: GET /cases/{app_uid}/output-documents

Return a list of generated Output Documents for a given case.

GET /api/1.0/{workspace}/cases/{app_uid}/output-documents

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-documents
app_uidUnique ID of case/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-documents

Result:

If successful, the HTTP status code is set to 200 and it returns the following array of objects with information about the generated Output Documents in the case:
[Start array.
{Start first Output Document object.
"app_doc_uid",Unique ID of generated case document.
"app_doc_filename",Filename of the generated output document file. If
"doc_uid",Unique ID of the Output Document definition.
"app_doc_version",Number of the version of the generated Output Document, which is 1 for the first time it is generated, 2 for the second, etc.
"app_doc_create_date",Datetime in "YYYY-MM-DD HH:MM:SS" format when the Output Document was generated. Hours are on a 24 clock system.
"app_doc_create_user",The user who generated the Output Document in "last-name, first-name (username)" format.
"app_doc_type",Type of document which is "OUTPUT DOC" if generating a MS Word file, "OUTPUT PDF" if generating a PDF file, or "OUTPUT BOTH" if generating both types of files.
"app_doc_index",The index number of files in the case, which starts counting all uploaded Input Document files, generated Output Documents and attached files (from file fields in DynaForms), so the first file is 1, the second is 2, etc. Note that a new index number is generated for each version of a generated Output Document.
"app_doc_link",The relative link to download the generated Output Document file in the format "cases/cases_ShowOutputDocument?a={app_doc_uid}&v={version}&ext={extension}&random={random}", where the version is 1 if the first time it is generated, 2 for the second time it is generated, etc. The extension can be pdf or doc. If available in both formats then it will be pdf and needs to be caused to doc to download the MS Word file. To form the complete URL to download the file, prepend "http://{domain}/sys{workspace}/{lang}/{skin}/" to this relative URL, such as "https://example.com/sysworkflow/en/neoclassic/"
},End first Output Document object array.
...Any additional Output Document objects.
]End array.

For example:

[
   {
      "app_doc_uid":         "14155521453271dd8a16fd9010864110",
      "app_doc_filename":    "Output 2.pdf",
      "doc_uid":             "10401087752fa8bc6f0cab6048419434",
      "app_doc_version":     1,
      "app_doc_create_date": "2014-03-17 12:07:52",
      "app_doc_create_user": "Jones, Mary (maryj)",
      "app_doc_type":        "OUTPUT PDF",
      "app_doc_index":       1,
      "app_doc_link":        "cases/cases_ShowOutputDocument?a=14155521453271dd8a16fd9010864110&v=1&ext=pdf&random=1910389699"
   },
   {
      "app_doc_uid":         "30145523653271ddb4b7936097604166",
      "app_doc_filename":    "asdsa.pdf",
      "doc_uid":             "67423604152fa88941c44d5089456849",
      "app_doc_version":     1,
      "app_doc_create_date": "2014-03-17 12:07:55",
      "app_doc_create_user": ", Administrator (admin)",
      "app_doc_type":        "OUTPUT BOTH",
      "app_doc_index":       2,
      "app_doc_link":        "cases/cases_ShowOutputDocument?a=30145523653271ddb4b7936097604166&v=1&ext=pdf&random=996247643"
   }
]

Note that if the logged-in user doesn't have rights to view the generated Output Documents or if there are no generated Output Documents in the case, then an empty array will be returned.

PHP Example

This example downloads the generated DOC file for each Output Document. The generated DOC file is really just an HTML file which has a ".doc" extension added, so it can be opened and searched like a normal text file, once it has been converted to plain text. This code uses strip_tags() to remove the HTML tags and uses preg_replace() to replace the

and
tags with new lines (\n). Then, it searches for "Due Date: ..." in the plain text, and then prints out the filename and its due date for each Output Document.

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "silvia", "p4sSw0rD");

$caseId = '14822205755e60222b0ca68094757835';
$url  = "/api/1.0/workflow/cases/$caseId/output-documents";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   foreach ($oRet->response as $oDoc) {
      $link = "http://localhost:301/sysworkflow/en/neoclassic/" . $oDoc->app_doc_link;
      //get the DOC instead of the PDF file to text searches:
      $link = str_replace('&ext=pdf', '&ext=doc', $link);
      $contents = file_get_contents($link) or die("Error: Unable to get file:\n$link");
   
      //strip HTML tags and replace <p> and <br> with new lines.
      $contents = strip_tags($contents, "<br><p>");
      $contents = preg_replace('/<(br|p)*?>/i', "\n", $contents);
      $contents = html_entity_decode($contents);
   
      //If found "Due Date: (...)\n", then get the date:    
      if (preg_match('/Due Date: (.+?)$/mi', $contents, $matches))  
         $dueDate = $matches[1];
      else
         $dueDate = "NO_DATE";
         
      print "File {$oDoc->app_doc_filename} is due $dueDate.\n";
   }
}

Get Output Document: GET /cases/{app_uid}/output-document/{app_doc_uid}

Return a generated Output Document for a given case.

GET /api/1.0/{workspace}/cases/{app_uid}/output-document/{app_doc_uid}

Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_uidUnique ID of the case/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_doc_uidUnique ID of the case document/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166

Result:

If successful, it returns an HTTP status code of 200 and an object containing information about the specified output document, such as:

{
   "app_doc_uid":         "30145523653271ddb4b7936097604166",
   "app_doc_filename":    "clientBill.pdf",
   "doc_uid":             "67423604152fa88941c44d5089456849",
   "app_doc_version":     1,
   "app_doc_create_date": "2014-03-17 12:07:55",
   "app_doc_create_user": "Jones, Mary (mary)",
   "app_doc_type":        "OUTPUT BOTH",
   "app_doc_index":       2,
   "app_doc_link":        "cases/cases_ShowOutputDocument?a=30145523653271ddb4b7936097604166&v=1&ext=pdf&random=996247643"
}

PHP Example

Download the generated PDF file for an Output Document and save it to the local harddrive.

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "silvia", "p4sSw0rD");

$caseId    = '14822205755e60222b0ca68094757835';
$caseDocId = '55757090055e4d643040a15027216052';
   
$url = "/api/1.0/workflow/cases/$caseId/output-document/$caseDocId";
$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   $link = "http://localhost:301/sysworkflow/en/neoclassic/" . $oRet->response->app_doc_link;
   //Download binary PDF file:
   $handle = fopen($link, "rb") or die("Error: Unable to open file:\n$link");
   $contents = stream_get_contents($handle) or die("Error: Unable to get file:\n$link");
   fclose($handle);  
   
   //save file to a app_doc_filename on local harddrive
   file_put_contents('home/foo/reports/' . $oRet->response->app_doc_filename, $contents) or
      die("Error: Unable to save file to harddrive:\n" . $oRet->response->app_doc_filename);
}

Generate Output Document: POST /cases/{app_uid}/{del_index}/output-document/{app_doc_uid} (>= version 3.0.0.5)

Available in version 3.0.0.5 and later.

Generate a specified Output Document for a given case, meaning that a PDF, a DOC or both files (depending on options selected in the definition of the Output Document) will be created, inserting any variables in the template.

If the Output Document already exists, then it will be regenerated. If versioning is enabled, then the regenerated files will be given a new version number and document index number, but if versioning is NOT enabled, then the existing files will be overwritten with the same version number and document index number.

POST /api/1.0/{workspace}/cases/{app_uid}/{del_index}/output-document/{out_doc_uid}

URL Parameters:

NameDescriptionExample
workspaceWorkspace name.https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288
app_uidUnique ID of the case.https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288
del_indexThe delegation index, which counts the assignment of tasks to users, where the first assigned task is 1, the second is 2, etc. https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288
out_doc_uidThe unique ID of the Output Document, which can be obtained by clicking on the Show ID button when viewing the list of Output Documents.https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/2/output-document/12135961857509fd4833312019691288

POST fields:

None.

Result:

TypeDescription
objectReturns an object with information of the generated document

Example:

Response

If the Output Document was successfully generated, then the HTTP status code is set to 200 and it returns a object with information about the generated Output Document, such as:

{
   "app_doc_uid":         "30145523653271ddb4b7936097604166",
   "app_doc_filename":    "sample.pdf",
   "doc_uid":             "67423604152fa88941c44d5089456849",
   "app_doc_version":     1,
   "app_doc_create_date": "2014-03-17 12:07:55",
   "app_doc_create_user": "Administrator (admin)",
   "app_doc_type":        "OUTPUT BOTH",
   "app_doc_index":       2,
   "app_doc_link":        "cases/cases_ShowOutputDocument?a=30145523653271ddb4b7936097604166&v=1&ext=pdf&random=996247643"
}

PHP Example

Generate the Output Document and then force the PDF file to be downloaded as an attachment by the user's web browser.

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "silvia", "p4sSw0rD");

$caseId   = '14822205755e60222b0ca68094757835';
$delIndex = 2;
$outDocId = '39558947555df747738bc05034476159';
$url = "/api/1.0/workflow/cases/$caseId/$delIndex/output-document/$outDocId";
$oRet = pmRestRequest("POST", $url, null, $oToken->access_token);

if ($oRet->status == 200) {
   $link = 'http://' .$_SERVER['SERVER_NAME']. '/sysworkflow/en/neoclassic/' . $oRet->response->app_doc_link;
   //Download binary PDF file:
   $handle = fopen($link, "rb") or die("Error: Unable to open file:\n$link");
   $contents = stream_get_contents($handle) or die("Error: Unable to get file:\n$link");
   fclose($handle);  
   
   //serve up the PDF file for download as attachment in user's browser:
   header('Content-Description: File Transfer');
   header('Content-Type: application/octet-stream');
   header('Content-Disposition: attachment; filename="' . $oRet->response->app_doc_filename . '"');
   header('Content-Transfer-Encoding: binary');
   header('Expires: 0');
   header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
   header('Pragma: public');
   header('Content-Length: ' . strlen($contents));
   print $contents
   die;            //die here so that ?> at end of script isn't printed
}

Generate Output Document: POST /cases/{app_uid}/output-document (<= version 3.0.0.4)

Available in versions 2.8.0 to 3.0.0.4.

Generate a specified Output Document for a given case, meaning that a PDF, a DOC or both files (depending on options selected in the definition of the Output Document) will be created, inserting any variables in the template.

If the Output Document already exists, then it will be regenerated. If versioning is enabled, then the regenerated files will be given a new version number and document index number, but if versioning is NOT enabled, then the existing files will be overwritten with the same version number and document index number.

POST /api/1.0/{workspace}/cases/{app_uid}/output-document

URL Parameters:

NameDescriptionExample
workspaceWorkspace name.https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document
app_uidUnique ID of the case.https://example.com/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document

POST fields:

NameDescriptionExample
out_doc_uidUnique ID of the Output Document definition.

Result:

TypeDescription
objectReturns an object with information of the generated document

Example:
Request

{
   "out_doc_uid": "1265557095225ff5c688f46031700471"
}

Response

If the Output Document was successfully generated, then the HTTP status code is set to 200 and it returns a object with information about the generated Output Document, such as:

{
   "app_doc_uid":         "30145523653271ddb4b7936097604166",
   "app_doc_filename":    "sample.pdf",
   "doc_uid":             "67423604152fa88941c44d5089456849",
   "app_doc_version":     1,
   "app_doc_create_date": "2014-03-17 12:07:55",
   "app_doc_create_user": "Administrator (admin)",
   "app_doc_type":        "OUTPUT BOTH",
   "app_doc_index":       2,
   "app_doc_link":        "cases/cases_ShowOutputDocument?a=30145523653271ddb4b7936097604166&v=1&ext=pdf&random=996247643"
}

PHP Example

Generate the Output Document and then force the PDF file to be downloaded as an attachment by the user's web browser.

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "silvia", "p4sSw0rD");

$caseId   = '14822205755e60222b0ca68094757835';
$outDocId = '39558947555df747738bc05034476159';
$aVars = array(
   'out_doc_uid' => $outDocId
);  
   
$url = "/api/1.0/workflow/cases/$caseId/output-document/";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   $link = "http://localhost:301/sysworkflow/en/neoclassic/" . $oRet->response->app_doc_link;
   //Download binary PDF file:
   $handle = fopen($link, "rb") or die("Error: Unable to open file:\n$link");
   $contents = stream_get_contents($handle) or die("Error: Unable to get file:\n$link");
   fclose($handle);  
   
   //serve up the PDF file for download as attachment in user's browser:
   header('Content-Description: File Transfer');
   header('Content-Type: application/octet-stream');
   header('Content-Disposition: attachment; filename="' . $oRet->response->app_doc_filename . '"');
   header('Content-Transfer-Encoding: binary');
   header('Expires: 0');
   header('Cache-Control: must-revalidate, post-check=0, pre-check=0');
   header('Pragma: public');
   header('Content-Length: ' . strlen($contents));
   print $contents
   die;            //die here so that ?> at end of script isn't printed
}

Delete Output Document: DELETE /cases/{app_uid}/output-document/{app_doc_uid}

Remove a generated Output Document from a case.

DELETE /api/1.0/{workspace}/cases/{app_uid}/output-document/{app_doc_uid}

Note: This endpoint does not delete the record for the generated Output Document located in the wf_{workspace}.APP_DOCUMENT table in the database, nor does it delete the physical file(s) from the file system which are located at: {Install-Directory}/shared/sites/{workspace}/files/XXX/XXX/XXX/XXXXXXXXXXXXXXXX/outdocs/{app_doc_uid}, where XXX... is the app_uid. Instead, it simply changes the value of the wf_{workspace}.APP_DOCUMENT.APP_DOC_STATUS field in the database from "ACTIVE" to "DELETED" so that the files can not be seen in the ProcessMaker interface. Writing to the database to change this value back to "ACTIVE" will undelete the file.

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_uidUnique ID of the case/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166
app_doc_uidUnique ID of the case document/api/1.0/workflow/cases/29113740655cb9656d4ca19088692497/output-document/30145523653271ddb4b7936097604166

Result:

If the generated Output Document was removed, then it returns an HTTP status code of 200 and no response object.

Example:

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "silvia", "sample");

$caseId = '14822205755e60222b0ca68094757835';
$caseDocId = '62062886955e6022776e618009059390';  
$url = "/api/1.0/workflow/cases/$caseId/output-document/$caseDocId";

$oRet = pmRestRequest("DELETE", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   print "Output Document deleted.\n";  
}

Cases Notes

The following endpoints are used to manipulate case notes:

  1. Get a list of notes for a case: GET /cases/{app_uid}/notes
  2. Get a page of notes for a case: GET /cases/{app_uid}/notes/paged
  3. Create a new note for a case: POST /cases/{app_uid}/note/

Get Case Notes: GET /cases/{app_uid}/notes

Get a list of the case notes for a specified case.

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

Parameters:

NameDescriptionDefaultExample
workspaceWorkspace name/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes
app_uidUnique ID of the case where the notes are attached./api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes
Filters for case notes
start={num}Optional. Number where the list of notes starts.0/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?start=30
limit={num}Optional. The number of notes to list.25/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?limit=10
sort={field}Optional. Field used to order the list, which is one of the APP_NOTES fields)APP_NOTES.NOTE _DATE/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?sort=APP_NOTES.USR_UID
dir={dir}Optional. Order which notes are listed: asc, descdesc/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?dir=asc
usr_uid={uid}Optional. Unique ID of the user who posted the case note./api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?usr_uid=86994841555ce4e51406a80055794876
date_from={date}Optional. Notes which were created from this date on, in "YYYY-MM-DD" format. /api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?date_from=2015-01-31
date_to={data}Optional. Notes which were created up to (but not including) this date in "YYYY-MM-DD" format. /api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes?date_to=2015-12-31
search={text}Optional. Search for notes with the specified text in the note's content. Make sure to URL encode in UTF-8 the searched text, 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/57793680455e7a4326b71f5064060314/notes?search=contract%20details

Result:

If successful, the HTTP status code is set to 200 and the response is a array of case note objects:

[Start array.
{Start first case note object.
"app_uid", The unique ID of the case where the note is attached.
"usr_uid", The unique ID of the user who added the note.
"note_date",The date when the note was added in "YYYY-MM-DD HH:MM:SS" format.
"note_content"The content of the case note.
},The date when the note was added in "YYYY-MM-DD HH:MM:SS" format.
...Any additional case notes.
]End array.

For example:

[
  {
    "app_uid":      "17969179752e27c4b3027c3006962937",
    "usr_uid":      "00000000000000000000000000000001",
    "note_date":    "2015-06-01 12:12:12",
    "note_content": "This case needs more review before approval is given."
  },
  {
    "app_uid":      "17969179752e27c4b3027c3006962937",
    "usr_uid":      "39558947555df747738bc05034476159",
    "note_date":    "2015-06-01 16:12:12",
    "note_content": "Please check the services rendered in this contract."
  }
]

Note: Only users who have been assigned Process Permissions to case notes may access them. Even the user who is currently assigned to work on the case may not see the case notes without Process Permission for case notes. If the logged-in user doesn't have proper permissions to access case notes, the following error object is returned:

{
   "error": {
      "code":    400,
      "message": "Bad Request: You do not have permission to access the cases notes"
   }
}

PHP Example:

Prints out the notes for a case. Looks up information about users to add the full name and username to notes.

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "mary", "p4sSw0rD");

$caseId = '78014942855e4a66cb0f531062309584';
$url = "/api/1.0/workflow/cases/$caseId/notes";

$oRet = pmRestRequest("GET", $url, null, $oToken->access_token);
if ($oRet->status == 200) {

   //get users to display their full names for each note:
   $url = "/api/1.0/workflow/users";
   $aUsers = pmRestRequest("GET", $url, null, $oToken->access_token);
   
   $aUserInfo = array(); //empty array to hold info about users.
   foreach ($aUsers as $oUser)
      $aUserInfo[$oUser->usr_uid] = "{$oUser->usr_firstname} {$oUser->usr_lastname} ({$oUser->usr_username})";
   
   foreach ($oRet->response as $oNote) {
      $sUser = $aUsers[$oNote->usr_uid];
      print "<p>{$oNote->note_content}<br>
         "
<small>Posted by $sUser on {$oNote->note_date}</small></p>";
   }
}

Get Page of Case Notes: GET /cases/{app_uid}/notes/paged

Get a page of the cases notes for a specified case.

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

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes/paged
app_uidUnique ID of case/api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes/paged
filtersOptional. Any of the filters listed above./api/1.0/workflow/cases/57793680455e7a4326b71f5064060314/notes/paged?search=contract

Result:

If successful, the HTTP status code is set to 200 (OK) and the response is a page object with information about the results and an array of case note objects in the data member, such as:

{
   "total":     2,
   "start":     0,
   "limit":     25,
   "sort":      "APP_NOTES.NOTE_DATE",
   "dir":       "DESC",
   "usr_uid":   "",
   "date_to":   "",
   "date_from": "",
   "search":    "",
   "data":
   [
      {
         "app_uid":      "115968518533473068ad299078535175",
         "usr_uid":      "39558947555df747738bc05034476159",
         "note_date":    "2015-03-28 11:10:51",
         "note_content": "Is the purchase price too high for office furniture?"
      },
      {
         "app_uid":      "115968518533473068ad299078535175",
         "usr_uid":      "00000000000000000000000000000001",
         "note_date":    "2015-03-28 17:19:45",
         "note_content": "I have approved the purchase request, despite the high price."
      }
   ]
}

Note: Only users who have been assigned Process Permissions to case notes may access them. Even the user who is currently assigned to work on the case may not see the case notes without Process Permission for case notes. If the logged-in user doesn't have proper permissions to access case notes, the following error object is returned:

{
   "error": {
      "code":    400,
      "message": "Bad Request: You do not have permission to access the cases notes"
   }
}

Create Case Note: POST /cases/{app_uid}/note

Create a new case note for a given case. Note that only users who are currently assigned to work on the case or have Process Permissions to access case notes may create a case note.

POST /api/1.0/{workspace}/cases/{app_uid}/note

URL Parameters:

NameDescriptionExample
workspaceWorkspace name/api/1.0/workflow/cases/115968518533473068ad299078535175/note
app_uidUnique ID of the case./api/1.0/workflow/cases/115968518533473068ad299078535175/note

POST Fields:

NameDescription
note_contentContent of the case note in plain text. Use \n to insert a new line in the text.
send_mailOptional. Set to 1 to send an email with the content of the case note in its body to all the participants in the case. The default is 0, which doesn't send an email. Note that this endpoint adds the emails to the queue, but they only sent out when the cron.php file executes.

Result:

If the case note was created, then the HTTP status code is set to 200 (OK) and there is no return value. If the status code is 300 or higher then an error occurred, and an error object will usually be returned, such as:

{
   error: {
      "code":    400,
      "message": "Bad Request: You do not have permission to access the cases notes"
   }
}

PHP Example:

The following example creates a new case note, which is sent out in an email to all the participants in the case:

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "mary", "p4sSw0rD");

$caseId = '57793680455e7a4326b71f5064060314';
$aVars = array(
   'note_content' => "Please review the Invoice totals.\nThey look too low to cover the costs",
   'send_mail'    => 1
);
   
$url = "/api/1.0/workflow/cases/$caseId/note";
$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200) {
   print "Case note added.";
}

Mobile Endpoints

The following endpoints are used by the ProcessMaker App installed on mobile devices. Although originally designed for the mobile app, these endpoints can be used in any context and they often return more information than the normal REST endpoints. They are defined in workflow/engine/src/ProcessMaker/Services/Api/Light.php and call code in workflow/engine/src/ProcessMaker/BusinessModel/Light.php.

Create case file record(s): POST /light/case/{app_uid}/upload

Create new case file record(s) in a specified case. These case files can be attached files (used by File controls), Input Document files, or Output Document files in version 1.0.1.8 and later. In version 1.0.1.7 and earlier, the case files can only be attached files. (Note that case files are known as AppDocuments in ProcessMaker).

This endpoint adds new record(s) in the APP_DOCUMENT table and stores their filename(s) in the CONTENT table in the database. It returns the generated case file ID and version number for each file. This information can then be used to call the POST /light/case/{app_uid}/upload/{app_doc_uid} endpoint to upload each file.

POST /api/1.0/{workspace}/light/case/{app_uid}/upload

URL Parameters:

NameDescriptionExample
workspaceWorkspace namehttps://example.com/api/1.0/workflow/cases/115968518533473068ad299078535175/upload
app_uidUnique ID of the case.https://example.com/api/1.0/workflow/cases/115968518533473068ad299078535175/upload

POST Fields:

ExampleDescription
[ Start array of objects.
{ Start object, which holds information about the case file.
"name": "scannedReceipts2016-05.jpg", Required. The filename of the file which will later be uploaded with POST /light/case/{app_uid}/upload/{app_doc_uid}.
"appDocType": "INPUT", Optional, available in version 1.0.1.8 and later. The type of case file, which can be:
"ATTACHED": an attached file which is uploaded to a File control which isn't associated with an Input Document,
"INPUT": an Input Document file (or uploaded to a File control which is associated with an Input Document),
"OUTPUT": an Output Document file. Note: Instead of this option, it is recommended to use POST /cases/{app_uid}/output-document to generate Output Document files.
If not included, then set to "ATTACHED" by default.
"docUid": "26489274557325e0cefb242036509648",Optional, available in version 1.0.1.8 and later. The unique ID of the Input Document or Output Document. Set to -1 for an attached file which is uploaded through a file control which isn't associated with an Input Document. If not included then set to -1 by default.
"fieldName": "receiptFile" Optional, available in version 1.0.1.8 and later. The name of the File control where the file will be uploaded. If uploaded to File controls inside a grid, set to "GridVariable_RowNumber_FileFieldName". For example, a value of "clientList_2_contractFile", means that the file was uploaded to the second row of a grid whose variable is "clientList" and whose File field has the name "contractFile". If the file will be uploaded in an Input Document step (not a File control in a Dynaform), then set to NULL or do not include this parameter.
} End object.
{...} Any additional objects with information about case files, which will later be uploaded.
] End array of objects.

Result:

If the case file record(s) were created, then the HTTP status code is set to 200 (OK) and an array of objects is returned with the following information about the generated case file record(s):

ExampleDescription
[ Start array of objects.
{ Start object, which holds information about the new case file record.
"docVersion": 1, The document version number which will always be 1 for the first version of the case file.
"appDocUid" : "82749015357325e0d1cfef6058054658"The generated unique ID for the new case file.
} End object.
{...} Any additional objects with information about new case files.
] End array of objects.

If a bad case ID is specified, then the HTTP status code will be set to 400 and the following error object will be returned:

{
   error: {
      "code":    400,
      "message": "Bad Request: this case has 0 delegations"
   }
}

If the "name" parameter is not included, then the HTTP status code is set to 200 and the response is NULL.

Example:

Request:

[
  {  //attached file uploaded through Home > Documents
     "name": "requestedBudget.xls"
  },
  {  //attached file uploaded to File control with the name "employeePhoto" in a DynaForm
     "name":      "johnDoePhoto.jpg",
     "fieldName": "employeePhoto"  
  },
  {  //attached file uploaded to File control with the name "receiptFile" in the first row of grid with "receiptList" variable
     "name":      "officeSupplies.doc",
     "fieldName": "receiptList_1_receiptFile"  
  },
  {  //attached file uploaded to File control with the name "receiptFile" in the second row of grid with "receiptList" variable
     "name":      "newOfficeFurniture.doc",
     "fieldName": "receiptList_2_receiptFile"  
  },
  {  //Input Document file associated with a File control with the name "contractFile"
     "name":      "AcmeServicesContract.pdf",
     "appDocType":"INPUT",
     "docUid":    "26489274557325e0cefb242036509648",
     "fieldName": "contractFile"
  },
  {  //Input Document file (which is uploaded in an Input Document step and not a File control)
     "name":      "NewWidgetPrices.xls",
     "appDocType":"INPUT",
     "docUid":    "1a8598f3d7d6ce40dc2abbdbd7cdaa49"
  },
]

Response:

[
  {  
     "docVersion": 1,
     "appDocUid" : "189395356573278c8b2d799089824447"
  },
  {  
     "docVersion": 1,
     "appDocUid" : "201295905573278c8e45438092199134"
  },
  {  
     "docVersion": 1,
     "appDocUid" : "9886722215731415bb671a0038276864"
  },
  {  
     "docVersion": 1,
     "appDocUid" : "24454306957325ad4205899098323500"
  },
  {  
     "docVersion": 1,
     "appDocUid" : "35313659957324f217ccda7000260391"
  },
  {  
     "docVersion": 1,
     "appDocUid" : "5876481515732526a093938002875566"
  },
]

PHP Example:

The following example creates a file case record for an Input Document file which is associated with a File control which has the name "expenses".

$oToken = pmRestLogin("BDBSKDWPZCMDZPSXPOHAXCMZQZLMLCQV", "25253873955e0e542943e80035324554", "mary", "p4sSw0rD");

$caseId = '9886722215731415bb671a0038276864';
$url = "/api/1.0/workflow/light/case/$caseId/upload";
$filePath = '/home/amos/Pictures/ReceiptListAmountFieldRed.png';
$aVars = array(
  array(
    'name'       => 'newFurnitureReceipt.jpeg',
    'appDocType' => 'INPUT',
    'docUid'     => '26489274557325e0cefb242036509648',
    'fieldName'  => 'expenses'
  )
);

$oRet = pmRestRequest("POST", $url, $aVars, $oToken->access_token);

if ($oRet->status == 200 and is_array($oRet->response)) {
  $caseFileId = $oRet->response[0]->appDocUid;
  $docVersion = $oRet->response[0]->docVersion;
}