Please rate how useful you found this document: 
Average: 2.1 (8 votes)

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:

Parameter Description Example
workspace Workspace name which by default is "workflow". /api/1.0/workflow/cases/37213410154d375de3e3620044382558/variables
app_uid Case'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?del_index={del_index}

Set variable(s) in a case.

Permission:

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

Structure:

PUT /api/1.0/{workspace}/cases/{app_uid}/variable?del_index={del_index}

URL Parameters:

Parameter Description Example
workspace Workspace name which by default is "workflow". /api/1.0/workflow/cases/37213410154d375de3e3620044382558/variable
app_uid Case's unique ID. /api/1.0/workflow/cases/37213410154d375de3e3620044382558/variable
del_index Case's delegation index to get the thread information, which can be obtained from the @%INDEX system variable. /api/1.0/workflow/cases/37213410154d375de3e3620044382558/variable?del_index=1

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 del_index = 1 //the case is in Draft status;
var url = "/api/1.0/workflow/cases/" + caseId + "/variable?del_index = "+ del_index;;
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';
$del_index = 1 //the case is in Draft status;
$url = "/api/1.0/workflow/cases/$caseId/variable?del_index=$del_index";
$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 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:

Parameter Description Example
workspace Workspace name which by default is "workflow". /api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientName
app_uid Case's unique ID. /api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientName
del_index Case's delegation index, which can be obtained from the @%INDEX system variable. /api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientName
var_name Name 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 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}/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:

Parameter Description Example
workspace Workspace name which by default is "workflow". /api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged
app_uid Case's unique ID. /api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged
del_index Case's delegation index, which can be obtained from the @%INDEX system variable. /api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged
var_name Name of the case variable. /api/1.0/workflow/case/37213410154d375de3e3620044382558/2/variable/clientList/paged

Optional URL Parameters:

Parameter Description Example
filter A case-insensitive search in grid fields. Only rows whose fields contain the filter string are returned. .../paged?filter=catering
lfilter A case-insensitive search in the beginning of grid fields. Only rows whose fields start with the filter string are returned. .../paged?lfilter=e-z
rfilter A case-insensitive search in the end of grid fields. Only rows whose fields end with the filter string are returned. .../paged?rfilter=23484
start The 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
limit The 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:

name name_label address address_label contractDate_label contractDate currentClient currentClient_label
EZ-Catering EZ-Catering 234 W. 11th St. Bloomington IN 23484 234 W. 11th St. Bloomington IN 23484 2016-05-31 2016-05-31 00:00:00 1 true
Smithee Lawn Service Smithee Lawn Service 555 Main St. Evansville IN 46234 555 Main St. Evansville IN 46234 2016-05-08 2016-05-08 00:00:00 0 false
Best Accounting Services Best Accounting Services 4332 Oak St. Putnamville, IN 46234 4332 Oak St. Putnamville, IN 46234 2016-05-16 2016-05-16 00:00:00 1 true

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

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

Permission:

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

Structure:

POST /api/1.0/{workspace}/variable/{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:

Parameter Description Example
workspace Workspace name which by default is "workflow". http://example.com/api/1.0/workflow/variable/37213410154d375de3e3620044382558/2/variable/clientName
app_uid Case's unique ID. http://example.com/api/1.0/workflow/variable/37213410154d375de3e3620044382558/2/variable/clientName
del_index Case's delegation index, which can be obtained from the @%INDEX system variable. http://example.com/api/1.0/workflow/variable/37213410154d375de3e3620044382558/2/variable/clientName
var_name Name of the case variable. http://example.com/api/1.0/workflow/variable/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/variable/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/variable/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/variable/$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/variable/$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 /variable/{app_uid}/{del_index}/variable/{var_name}

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

Permission:

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

Structure:

PUT /api/1.0/{workspace}/variable/{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.

URL Parameters:

Parameter Description Example
workspace Workspace name which by default is "workflow". http://example.com/api/1.0/workflow/variable/37213410154d375de3e3620044382558/2/variable/clientName
app_uid Case's unique ID. http://example.com/api/1.0/workflow/variable/37213410154d375de3e3620044382558/2/variable/clientName
del_index Case's delegation index, which can be obtained from the @%INDEX system variable. http://example.com/api/1.0/workflow/variable/37213410154d375de3e3620044382558/2/variable/clientName
var_name Name of the case variable. http://example.com/api/1.0/workflow/variable/37213410154d375de3e3620044382558/2/variable/clientName

POST Parameters:

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

Result:

If the variable was updated, then the endpoint returns 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/variable/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/variable/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/variable/$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}

Delete a variable in a case.

Permission:

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

Structure:

DELETE /api/1.0/{workspace}/cases/{app_uid}/{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.

URL Parameters:

Parameter Description Example
workspace Workspace name which by default is "workflow". http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
app_uid Case's unique ID. http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName
del_index Case'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_name Name of the case variable. http://example.com/api/1.0/workflow/cases/37213410154d375de3e3620044382558/2/variable/clientName

Optional URL Parameters:

Parameter Description Example
?keys=X Delete 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";
}