3.2 - 3.8 - ProcessMaker Functions - Case Routing Functions

Case Routing Functions

PMFDerivateCase()

PMFDerivateCase() routes a case to the next task in the process.

Parameters:

• string caseUID: The unique ID of the case to be routed, which can be found with PMFCaseList() or by querying the field wf_<WORKSPACE>.APPLICATION.APP_UID. The case UID of the current case is stored in the system variable @@APPLICATION.
• int delegation: The delegation index of the task to be routed. The delegation index of the current case is stored in the system variable @%INDEX. Note that the delegation index changes with each new task in the case, so look up the index before calling this function.
• boolean executeTriggersBeforeAssigment: Optional parameter. By default, it is set as false. If set to true, any triggers that are set to be fired before the case is assigned to the next user will be fired before routing the case. It is not recommended to set the value to true, because then the function will generate an infinite loop. If this value is set to false the trigger will be executed before assignment.
• string userUID: Optional parameter. The unique ID of the user who is assigned to the task indicated by the delIndex number, which should be an open task. If not included or set to null, then it will be set to the unique ID of the current logged-in user.

Return Value:
Returns 1 if the new case was routed successfully; otherwise, returns 0 if an error occurred.

Note 1: If this function is called for the current task when running a case, then the case will be routed twice--once by PMFDerivateCase() and the second time by the interface running the case. To work around this problem, call the die() function after PMFDerivateCase() to stop the processing and prevent the second routing. However, if die() is called after a Dynaform step, then it will stop the Dynaform data from getting saved to the database. In this case, use PMFSendVariables() to save the data to the database before calling PMFDerivateCase and die(). See the example below.

Note 2: This function only works if the currently logged in user is assigned to the task indicated by the delegation parameter. If it is necessary to route a task that is assigned to another user, login as that user with web services and use routeCase() instead of PMFDerivateCase(). See this code example for routing past the next task in the current case.

Note 3: The PMFDerivateCase() function can only route tasks that exist in the wf_<WORKSPACE>.APP_DELEGATION table and whose status is 'OPEN'. In other words, this function can't be called on past tasks that are already closed and future tasks that don't yet exist. To route the next task in the case, which doesn't yet exist, see Skipping the Next Task in a Case.

Example 1:
Route the current case to the next task in the process and redirect the web browser back to Home > Inbox to see the case list:

Example 2:
To route to a case immediately after a Dynaform step, the data from the Dynaform variables needs to be stored in the database with PMFSendVariables() before calling die(). For example, the Dynaform contains the variables "firstName", "lastName", "address" and "telephone", which need to be saved.

Note: If the trigger is set before the next step (or before assignment if the last step in the task), then it is not necessary to call PMFSendVariables() because the variables from the Dynaform will have already been saved to the database.

Example 3:
To avoid having to click on the Continue button at the end of a task, create the following trigger, which is set before assignment:

If the next task is assigned to the same user as the current task, then it can be opened directly without going to the Inbox. Create the following trigger and set it to execute after routing:

jumping()

Note: Take into consideration that jumping() is not supported for Web Entries. The jumping() function redirects the user to the cases list, which does not apply to Web Entries.

jumping() routes a case to the next task in the process (or terminates the case if at the last task in the process) and then displays the case list.

Parameters:

• string caseUID: The unique ID of the case to be routed. For the current case, use the system variable @@APPLICATION. For other cases, use PMFCaseList() to obtain the case UID, or do a database query to look up the case's unique ID in the field wf_<WORKSPACE>.APPLICATION.APP_UID. Note that the case's UID changes with each new task.
• int delegation: The delegation index of the task to be routed. Counting starts from 1. For the current case, use the system variable @%INDEX. For other cases, use PMFCase() to obtain the delegation index, or do a database search in the field wf_<WORKSPACE>.APP_DELEGATION.DEL_INDEX.

Return Value:

None.

Example:

PMFRedirectToStep()

Warning: The PMFRedirectToStep function is not supported in the mobile version of Processmaker.

PMFRedirectToStep() redirects a case to any step in the current task. For the step to be executed, the specified step must exist and if it contains a condition, it must evaluate to true. Any pending variables in the case will be saved before redirecting and any triggers set to execute before the step will by executed before showing the step. Note that any trigger code after PMFRedirectToStep() is called will not be executed, so it should be used as the last command in the trigger code.

Parameters:

• string caseUID: The unique ID of a case. For the current case, use the system variable @@APPLICATION. For other cases, look it up using the PMFCaseList() function or by doing a database query for the field wf_<WORKSPACE>.APPLICATION.APP_UID.
• int delegation: The delegation index of a case. For the current case, use the system variable @%INDEX.
• string stepType: The type of step, which can be 'DYNAFORM', 'INPUT_DOCUMENT', 'OUTPUT_DOCUMENT', or 'EXTERNAL'.
• string stepUIDObject: The unique ID of the object (e.g. Dynaform, Input Document, Output Document, etc.) in the step. This unique ID can be found by looking up the wf_<WORKSPACE>.STEP.STEP_UID_OBJ field in the database.

Return Value:

None.

Example:

In the following code, the unique ID of the third step object is obtained with the executeQuery function after redirecting the task directly to the 3rd step with the PMFRedirectToStep function:

PMFGetNextAssignedUser()

PMFGetNextAssignedUser() returns an array of information about the user designated (i.e., chosen out of the assignment pool) to work on the next task in a specified case.

Parameters:

• string application: The unique ID of a case. For the current case, use the system variable @@APPLICATION. For other cases, use the PMFCaseList() function or caseList() web service. Alternatively, query the wf_<WORKSPACE>.APPLICATION.APP_UID or wf_<WORKSPACE>.APP_DELEGATION.APP_UID fields in the database
• string task: The unique ID of the task, which can be found by right clicking on the task in the process map and selecting Properties in the context menu. It can also be found with the taskList() web service or by querying the wf_<WORKSPACE>.TASK.TAS_UID field in the database.
• int delIndex: Optional. The delegation index of the current task in the case. It is only necessary to set this parameter if calling this function in a script task or if not calling this function for the current case.
• string userUID: Optional. The unique ID of the user assigned to the case. It is only necessary to set this parameter if calling this function in a script task or if not calling this function for the current case.

Return Value:
An associative array of information about the user to be designated to work on the next task in the specified case, with the following elements:

• string 'USR_UID': The unique ID of the next assigned user.
• string 'USR_USERNAME': The username of the next assigned user.
• string 'USR_FIRSTNAME': The first name of the next assigned user.
• string 'USR_LASTNAME': The last name of the next assigned user.
• string 'USR_EMAIL': The email address of the next assigned user.

Warning: This function only works reliably if called in certain circumstances; otherwise, it is recommended to get the next designated user by querying the wf_<WORKSPACE>.APP_DELEGATION.USR_UID field in the database in a trigger fired after routing. See this email example and this routing example.

This function should only be used when the next task in the process has cyclical assignment, since this function checks who was the last user designated to work on the next task (which is stored in the wf_<WORKSPACE>.TASK.TAS_LAST_ASSIGNED field in the database) and then returns the next user in the list. That next user will be assigned to the next case that routes to the task; however, the next case may not be the case specified by the $application parameter. Therefore, it is recommended to use this function in processes that do NOT have multiple cases being executed at the same time. If the process might execute multiple simultaneous cases, then only call this function in a trigger that fires before assignment.

Note: If this function is not called for the next task in the specified case, meaning that the $task is not the next task in the case, then the following error message will be displayed:
Fatal error: Call to a member function getTaskUid() on null in /opt/processmaker/workflow/engine/classes/class.case.php on line 2351

Example 1:
Send an email to the user designated to the next task in the current case, warning him/her about an upcoming case to work on. Send the first and last names of the next user as the variables @#firstname and @#lastname to insert into the email template:

Example 2:
In a script task, send out an email to the user designated to the next task in the current case, warning him/her about an upcoming case to work on. Because it is a script task, it is necessary to set the delegation index of the current task and the UID of the user. Since the @%INDEX in script tasks is stuck in the number from the last normal task, 1 needs to be added to get the index for the current task.

PMFGetNextDerivationInfo()

PMFGetNextDerivationInfo() retrieves the UID value, type of assignment of each task involved in the next routing and the UID values of the users and groups assigned to each one of these tasks. The function evaluates what the subsequent tasks will be based on the current case status.

• In case of a Gateway, the function evaluates the gateway conditions and the next task or tasks are returned. If these conditions are changed, then the function must be executed again to get the updated list of the next tasks.
• In the case of Valued Based Assignment, the variable is evaluated to define the next users.
• And in the case of parallel tasks, an array of all subsequent tasks is returned.

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 PMFCaseList(), WSCaseList(), or 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.

Return Value:

An array of associative arrays. Each one of these arrays contains the task ID, type of assignment, users and groups assigned to each one of the subsequent tasks. The array has the following structure:

Example:

The variable @@nextderivationinfo obtains the UID values of the users and groups, and the type of assignment of each task belonging to the next route in the current case. The return value will show: