Case Functions

PMFCaseList()

PMFCaseList() returns a list of the pending cases (i.e., cases that have a status of "To Do" or "Draft") belonging to a specified user. Note that the specified user must be designated to work on the current task of these cases.

array PMFCaseList(string userUID)

Parameters:

  • string userUID: The unique ID of a user who is assigned to work on the cases.

Return Value:

A list of cases, with the following structure:

[0] array ( associative array ( [string guid] [string name] [string status] [int delIndex] ) ) ...

Where:

  • string guid: The unique ID of a case.
  • string name: The label of a case.
  • string status: The status of a case.
  • int delIndex: The current delegation index.

Example:

@@GRID_CASES = PMFCaseList();

PMFTaskCase()

PMFTaskCase() returns all the tasks that have open delegations in the specified case.

array PMFTaskCase(string caseUID)

Parameters:

  • string caseUID: The unique ID of a case.

Return Value:

A list of tasks, with the following structure:

[0] array ( associative array ( [string guid] [string name] ) ) ...

Where:

  • string guid: The unique ID of a task.
  • string name: The name of a task.

Example:

 @@pendingTasksForCase = PMFTaskCase(@@APPLICATION);

PMFNewCase()

PMFNewCase() creates a new case starting in the specified task.

variant PMFNewCase(string processUID, string userUID, string taskUID, array variables, string status)

Parameters:

  • string processUID: The unique ID of the process, which can be found in the following ways:
    • Use the @@PROCESS system variable to get the unique ID of the current process.
    • Use the PMFProcessList() function or processList() web service.
    • Query the wf_<WORKSPACE>.PROCESS.PRO_UID field in the database or use a query like:
SELECT CON_ID FROM CONTENT WHERE CON_CATEGORY='PRO_TITLE' AND CON_VALUE='Expense Report Process'
  • string userUID: The unique ID of the user, which can be found in the following ways:
    • Use the @@USER_LOGGED system variable to get the unique ID of the user currently logged in.
    • Use the PMFUserList() function or userList() web service.
    • Query the wf_<WORKSPACE>.USERS.USR_UID field in the database.
  • string taskUID: The unique ID of the task, which can be found in the following ways:
    • Use the @@TASK system variable to get the unique ID of the current task.
    • Use the PMFTaskList() function or taskList() web service.
    • Query the wf_<WORKSPACE>.TASK.TAS_UID field in the database or get the starting task of the current process with the following query:
executeQuery("SELECT TAS_UID FROM TASK WHERE PRO_UID='" .@@PROCESS . "' AND TAS_START='TRUE'")
  • array variables: An associative array of the variables that will be sent to the case. The keys are the variable names and the values are the values of the case variables. If the case variable is a grid, then set the value to an associative array of associative arrays. See Example 3 below. If no variables are needed, then set to an empty array: array()
  • string status: (Optional) The new case status. If set to "TO_DO" the new case will be displayed directly in the user's inbox tray. If set to "DRAFT" or not included, the case will be displayed in the draft tray.

Return Value:

If an error occurred, it returns zero. Otherwise, it returns a string with the case UID of the new case.

Example 1:
Create a new case of the current process, designating the current user to work on the new case. The starting task ID is hard coded in the trigger code and no case variables are set in the new case. After creating the new case, call Cases::LoadCase() to find out the new case number and the name of its assigned user. Then, call the G::SendMessageText() function to display a message in the next screen about the new case.

$taskUID  = '7766592404f358fb90dcdc9043579725'; //set to the starting task's unique ID
$newCaseUID = PMFNewCase(@@PROCESS, @@USER_LOGGED, $taskUID, array(), "TO_DO");
//if a new case was created, display a message in the next screen:
$g = new G();

if ($newCaseUID) {
    $c = new Cases();
    $aCaseInfo = $c->LoadCase($newCaseUID, 1);
    $msg = 'New Case #' . $aCaseInfo['APP_NUMBER'] . ' is assigned to ' . $aCaseInfo["CURRENT_USER"];
    $g->SendMessageText($msg, 'INFO');
}
else {
    $msg = "Unable to create new case." . isset(@@__ERROR__) ? @@__ERROR__ : '';
    $g->SendMessageText($msg, 'ERROR');
}

Example 2:
Look up the ID of a process named "Expense Report Process" and its starting task in the database. Then, call the Derivation::getAllUsersFromAnyTask() method to get an array of the users who are assigned to that starting task. Use the rand() function to randomly choose one to assign to the new case. Set the values of case variables named "Model", "Price" and "OrderDate" in the new case.

//Look up the process UID
$result = executeQuery("SELECT CON_ID FROM CONTENT WHERE
   CON_CATEGORY='PRO_TITLE' AND CON_VALUE='Expense Report Process'"
);
$processUID = $result[1]['CON_ID'];

//Look up the UID of the starting task for the process:
$result = executeQuery("SELECT TAS_UID FROM TASK WHERE PRO_UID='$processUID' AND TAS_START='TRUE'");
$taskUID = $result[1]['TAS_UID'];

//Randomly choose a user from the list of assigned users for the starting task:
$d = new Derivation();
$aUsers = $d->getAllUsersFromAnyTask($taskId);
if (count($aUsers) == 0) {
    throw new Exception("There are no assigned users for task $taskUID.");
}
$noUser = rand(0, count($aUsers)-1);
$userUID = $aUsers[$noUser];

//Create an associative array of case variables named "Model", "Price" and "OrderDate":
$aData = array('Model' => 'Acme Coyote Trap', 'Price' => 29.99, 'OrderDate' => '2010-12-31');

PMFNewCase($processUID, $userUID, $taskUID, $aData);

Example 3:
Start a new case, setting a grid case variable named "clientsGrid" that has the fields "firstName", "lastName" and "telephone" and has 3 rows of data:

$taskUID  = '7766592404f358fb90dcdc9043579725'; //look up the starting task's unique ID
$aGrid = array(
    "1" => array("firstName" => "Greg",  "lastName" => "Brown", "telephone" = "471.826-4329"),
    "2" => array("firstName" => "Anne",  "lastName" => "Smith", "telephone" = "913.626-9518"),
    "3" => array("firstName" => "Sally", "lastName" => "Slim",  "telephone" = "765.652-8608")
);
$newCaseId = PMFNewCase(@@PROCESS, @@USER_LOGGED, $taskUID, array("clientsGrid" => $aGrid), "TO_DO");

PMFNewCaseImpersonate()

PMFNewCaseImpersonate() creates a new case. It is similar to PMFNewCase(), but it impersonates the session variables, so it is more robust than PMFNewCase().

string PMFNewCaseImpersonate(string processUID, string userUID, array variables, string taskUID)

Parameters:

  • string processUID: The unique ID of the process.
  • string userUID: The unique ID of the user.
  • array variables: An associative array of the variables that will be sent to the case. The array keys are the variable names and the array values are the values of the case variables. See PMFSendVariables() for the format of different variables in ProcessMaker. If no variables are needed, then set to an empty array: array()
  • string taskUID: Optional. The unique ID of the task where the case will start. If the process only has one starting task or the user is only assigned to one of the starting tasks, then it is not necessary to specify the task.

Return Value:

Returns the new case UID; otherwise, an error message will be displayed.

Note: The status of the new case will automatically be set to DRAFT. To change the status so the new case will appear in the user's Inbox (instead of the Draft box), see the Create new case and change its status section.

Example:

$aData = array('varname1' => 'varvalue1', 'varname2' => 'varvalue2', 'varname3' => 'varvalue3');
PMFNewCaseImpersonate(@@PROCESS, @@USER_LOGGED, $aData);

PMFPauseCase()

PMFPauseCase() pauses a specified case.

int PMFPauseCase(string caseUID, int delIndex, string userUID, string unpauseDate=null)

Parameters:

  • string caseUID: The unique ID of the case, which can be found in the following ways:
  • int delIndex: The delegation index of the current task in the case. For the current case, use the system variable @%INDEX.
  • string userUID: The unique ID of the user who will pause the case. Note that PMFPauseCase() allows any user to pause any case. The user's unique ID can be found in the following ways:
    • Get the UID of the currently logged-in user with the @@USER_LOGGED system variable or $_SESSION['USER_LOGGED'].
    • Use the PMFUserList() or WSUserList() functions, or the userList() web service.
    • Query the wf_<WORKSPACE>.USERS.USR_UID field in the database with executeQuery().
  • string unpauseDate: Optional. The datetime in the format "YYYY-MM-DD HH:MM:SS" indicates when the case will be unpaused. If set to NULL or "" (empty string), then the case will be paused indefinitely, until a user manually unpauses it. If the hours, minutes or seconds aren't included in the datetime, then they automatically set to zero. Note that the case will be automatically unpaused at the configured datetime by the cron.php script, so the server needs to periodically execute this script. Ex: "2015-12-31 17:59:59" or "2017-01-08"

Return Value:

Returns 1 if the case is paused successfully; otherwise, returns 0 if an error occurred.

Example:
Pause the current case. Then, call G::header() to redirect the web browser to the Inbox and call die() to stop the case from trying to advance to the next step.

PMFPauseCase(@@APPLICATION, @%INDEX, @@USER_LOGGED, "2016-09-23");
G::header("Location: casesListExtJsRedirector");
die();

Note: If calling die() in a trigger that is executed immediately after a Dynaform, it will prevent the form's data from being saved. Therefore it is recommended to set this trigger to execute before the next step in the task (or before assignment if the last step in the task), so that the form's data will be saved.

PMFUnpauseCase()

PMFunpauseCase() unpauses a specified case.

int PMFUnpauseCase(string caseUid, string delIndex, string userUID)

Parameters:

  • string caseUID: The unique ID of the case, which can be found in the following ways:
    • Use the @@APPLICATION system variable to get the unique ID of the current case.
    • Use the caseList() web service.
  • string delIndex: The delegation index of the current task in the case. For the current case, use the system variable @%INDEX.
  • string userUID: The unique ID of the user who will unpause the case, which can be found in the following ways:
    • Get the UID of the currently logged-in user with the @@USER_LOGGED system variable or $_SESSION['USER_LOGGED'].
    • Use the PMFUserList() or WSUserList() functions, or the userList() web service.
    • Query the wf_<WORKSPACE>.USERS.USR_UID field in the database with executeQuery().

Return Value:

Returns 1 if the case is unpaused successfully; otherwise, returns 0 if an error occurred.

PMFDeleteCase()

PMFDeleteCase() deletes a specified case. Note that the case will be deleted completely and it will not appear in the Participated tray. To cancel a case use PMFCancelCase() instead of PMFDeleteCase().

int PMFDeleteCase(string caseUID)

Parameters:

  • string caseUID: The unique ID of a case. For the current case use the system variable @@APPLICATION. Other case UIDs can be found with PMFCaseList(), WSCaseList(), caseList() or by querying the field wf_<WORKSPACE>.APPLICATION.APP_UID.

Return value:

  • Returns 1 if the case was successfully deleted, otherwise returns 0 if an error occurred.

Example:

@@return = PMFDeleteCase(@@APPLICATION);
G::header("Location: casesListExtJsRedirector");
die();

This example uses G::header() with Location: casesListExtJsRedirector to go back to the list of cases (inbox) after deleting the case.

PMFCancelCase()

PMFCancelCase() cancels a specified case in "TO DO" status. A cancelled case can be reviewed in the Participated tray. Use PMFDeleteCase for cases in "DRAFT" status that cannot be canceled.

int PMFCancelCase(string caseUID, int delIndex, string userUID)

Parameters:

  • string caseUID: The unique ID of the case, which can be found in the following ways:
  • int delIndex: The delegation index of the current task in the case. For the current case, use the @%INDEX system variable.
  • string userUID: The unique ID of the user who will cancel the case. For the currently logged-in user, use the @@USER_LOGGED system variable.

Return value:

  • Returns 1 if the case was successfully canceled.
  • Returns 0 if the case is in "DRAFT" status.

Example:

The following trigger code cancels the current case and uses the die() function to prevent the next step from being executed:

@@return = PMFCancelCase(@@APPLICATION, @%INDEX, @@USER_LOGGED);
if (@@return) {
    print "Case cancelled."
}
die;

PMFUnCancelCase()

Note: The PMFUnCancelCase() function is only available in version before ProcessMaker 3.2.1. As of ProcessMaker 3.2.2, the PMFUnCancelCase() function is named PMFRestoreCase().

PMFUnCancelCase() restores a cancelled case. A case cancelled can be reviewed in the inbox tray. Take into consideration that only roles with the PM_UNCANCELCASE permission will be able to uncancel a case.

int PMFUnCancelCase(string caseUID, string userUID)

Parameters:

  • string caseUID: The unique ID of the case, which can be found in the following ways:
  • string userUID: The unique ID of the user who will receive the case when uncancelling the case. For the currently logged-in user, use the @@USER_LOGGED system variable.

Return value:

Returns 1 if the case was successfully uncancelled, otherwise returns 0 if an error occurred. If the user does not have the PM_UNCANCELCASE permission assigned, it will return 0.

Example:

The following trigger code uncancels the current case and uses the die() function to prevent the next step from being executed:

@@return = PMFUnCancelCase(@@APPLICATION, @@USER_LOGGED);
print "Case uncancelled."
die;

PMFRestoreCase()

Note: Available as of ProcessMaker 3.2.2 on. The PMFRestoreCase() function was named PMFUnCancelCase() in versions before ProcessMaker 3.2.1.

PMFRestoreCase() restores a cancelled case. A case cancelled can be reviewed in the inbox tray. Take into consideration that only roles with the PM_UNCANCELCASE permission will be able to restore a case.

int PMFRestoreCase(string caseUID, string userUID)

Parameters:

  • string caseUID: The unique ID of the case, which can be found in the following ways:
  • string userUID: The unique ID of the user who will receive the case when uncancelling the case. For the currently logged-in user, use the @@USER_LOGGED system variable.

Return value:

Returns 1 if the case was successfully uncancelled, otherwise returns 0 if an error occurred. If the user does not have the PM_UNCANCELCASE permission assigned, it will return 0.

Example:

The following trigger code uncancels the current case and uses the die() function to prevent the next step from being executed:

@@return = PMFRestoreCase(@@APPLICATION, @@USER_LOGGED);
print "Case restored."
die;

PMFSendVariables()

PMFSendVariables() sends an array of case variables to a specified case in "TO_DO" status. These variables are stored in the wf_<WORKSPACE>.APPLICATION.APP_DATA field and can be displayed by any subsequent Dynaform that has a field name that is the same as the case variable name.

int PMFSendVariables(string caseUID, array variables)

Parameters:

  • string caseUID: The unique ID of the case that will receive the variable. Note that the case ID changes with each new task in the process. To send variables to the current case, use the system variable @@APPLICATION.
  • array variables: An associative array that will hold the case variables to sent to the case. The keys are the case variable names and the values are the values of the case variables.

Return Value:

Returns 1 if the variables were sent successfully to the case; otherwise, returns 0 if an error occurred.

Example:

$aData = array('Model' => 'Acme Blender #2', 'Price' => 27.40, 'OrderDate' => '2010-12-31');
PMFSendVariables(@@APPLICATION, $aData);

setCaseTrackerCode()

setCaseTrackerCode() sets the code and PIN of a case, which are used when an unregistered user logs into the Case Tracker to view the details of a particular case. By default, the code for a case is its case number and its PIN (public identification number) is a semi-random string of 4 characters (numbers and letters) autogenerated by ProcessMaker; however, setCaseTrackerCode() can set the case code and PIN to any desired values.

int setCaseTrackerCode(string caseUID, string code, string PIN = '')

Parameters:

  • string caseUID: The unique ID of a case. For the current case use the system variable @@APPLICATION. Other case UIDs can be found with PMFCaseList(), WSCaseList(), caseList() or by querying the wf_<WORKSPACE>.APPLICATION.APP_UID field in the database.
  • string code: The new code of a case up to 100 characters long, which will be stored in the wf_<WORKSPACE>.APPLICATION.APP_PROC_CODE field in the database. To keep the case code as the case number, set it to @@APP_NUMBER for the case number of the current case or for another case look up its case number in the wf_<WORKSPACE>.APPLICATION.APP_NUMBER field in the database.
  • string PIN: Optional. The new PIN (personal identification number) in UPPERCASE, which will be stored in the wf_<WORKSPACE>.APPLICATION.APP_PIN field as an MD5 hash and will be available in the system variable @@PIN for the current case. If not included or set to '' (an empty string), then the PIN will not be changed. Note that if the PIN is not in UPPERCASE, then it will not be possible to login to the Case Tracker.

Return Value:

If successful, returns one; otherwise returns zero or an error number.

Example:

setCaseTrackerCode(@@APPLICATION, '999', generateCode(4, 'ALPHANUMERIC'));