3.1 - Trigger Examples

Overview

Triggers provide a great deal of customization and flexibility to process design. These examples provide some ideas for more advanced uses of triggers.

Aborting New Cases Under Certain Circumstances

A trigger could be written to abort an existing case under certain circumstances. For instance, suppose there is a process where users should not open a new case if there is already an existing case which hasn't yet been completed (or canceled). The following trigger code could be inserted before the first step in the initial task to lookup whether there is already a case assigned to the current logged-in user whose APP_DELEGATION.DEL_THREAD_STATUS field is equal to 'OPEN', meaning that the task hasn't been completed (or canceled) yet.

If there is, then the new case which was just started will be deleted and a warning message will be displayed along with the summary of the existing case that the user should first complete.

Workaround for Global Variables

ProcessMaker does not have global variables, which can be used for all cases and processes. The best workaround for a global variable is to store values in a PM Table or an external database, and then look it up when needed with executeQuery(). When needing to permanently change the value of the variable, write to the database.

For example, a PM Table named "GLOBALS" could be created with the fields "VARIABLE" and "VALUE". To store the names of the managers of a company, the following data could be stored in the "GLOBALS" PM Table:

Then use the following query to look up the "CEO" global variable:

To set the "CEO" global variable to "Mary Marvin":

Note: In ProcessMaker 3.0+, PM Tables have "PMT_" prepended to their names in the wf_<WORKSPACE> database.

Global Counters for Cases

PM Tables can be used to implement global counters that can work across all cases. For example, if needing to keep a counter of the number of cases for each department in an organization, create a PM Table named "COUNTERS" with the fields "VARIABLE" and "VALUE" with the following contents:

Then, add a trigger to every case to increment the counter and display the number in the counter in a DynaForm when beginning a new case. For example a new case in the Finance department would execute the following trigger before the first step in the first task:

Then, add a field named "counter" to a subsequent DynaForm, so the value of the counter can be displayed to the user.

Note: In this case, the VALUE field is an INTEGER type, so its value doesn't need to be enclosed in single quotation marks like a CHAR or VARCHAR field.

Routing (Derivating) all Parallel Tasks in a Case

A trigger can be used to automatically route (derivate) all the the parallel tasks in a case. For example, if a purchase request is sent to 3 managers as 3 parallel tasks.

Once one manager makes a decision to approve or disapprove the purchase request, the case will automatically route on for all the other managers, so the first manager to make a decision will decide for the others and the case will be removed from the inbox of the other managers. The following trigger is fired after Dynaform of all parallel tasks.

Routing Parallel Tasks after Completing a Fixed Number

A process to approve expenses needs at least 3 out of 5 managers to review the expense before a decision can be made. The process has 5 parallel tasks which are assigned to each one of the managers.

The following trigger is fired After Routing of all the parallel tasks (which means that it will be fired after all the steps have been completed).

The trigger code checks to see whether at least two of the other parallel tasks have already been completed. Including the current task, that would mean that three tasks have been completed, so the rest of the parallel tasks will automatically be routed (derivated). The code looks up the assigned users for those tasks and logins as those users and calls the routeCase() web service for each task.

Displaying a List of Cases in a Grid

A grid with information and links to cases can be displayed in a DynaForm. For example, to display a list of cases for the currently logged in user in a grid, first create a grid named "casesGrid" with the fields "caseNumber" (textbox), "processName" (textbox), "taskName" (textbox), "dueDate"(date), "linkToCase" (link), "urlForCase" (hidden), and "labelForCase" (hidden).

Then, fire a trigger before DynaForm to populate the grid, with code like this:

Then, add the following JavaScript code to the DynaForm to set the links in the casesGrid:

Run the case, and the trigger will display a list of all the open cases for the current user:

Skipping the Next Task in a Case

If inside the current task, the rest of the steps in that task can be skipped by calling the PMFDerivateCase() function in a trigger. However, the PMFDerivateCase() function can't be called for tasks to which the current logged-in user is not assigned. Moreover, PMFDerivateCase() can't be called for tasks which don't yet have a record in the wf_<WORKSPACE>.APP_DELEGATION table and whose DEL_THREAD_STATUS field does not equal "OPEN". For these reasons, PMFDerivateCase() cannot be used to skip the next task in a case.

Instead, to skip the next task, create a trigger which fires After Derivation/Routing of the previous task. After derivation, a record has already been created in the wf_<WORKSPACE>.APP_DELEGATION table, so the assigned user and the delegation index for the next task can be looked up with executeQuery(). Also look up the MD5 hash for that user's password in the database. Then, login as that next assigned user with the login() web service and then call routeCase() to route through the next task.

For example:

If needing to execute this code in the middle of the previous task, first call PMFDerivateCase(), then execute the rest of the above code. At the end, call G::header() to redirect to the cases list and then call die(), to stop the previous task from trying to continue onto the next step.

Note: This code will have problems if the next task is a parallel task, because its index number might not be the maximum index number. In that case, search for a particular task ID in the APP_DELEGATION table. Task IDs can be found with the taskList() function.

Reopening Cases

After a case has been canceled or completed, it is not possible to reopen the case from the ProcessMaker interface. However, it is possible to reopen a case by calling the Cases::ReactivateCurrentDelegation() method to reactivate the last task in the case. Then, use the Cases::updateCase() to change the case's status from "CANCELLED" or "COMPLETED" to "TO_DO", so it will reappear in the user's Inbox. If using the Enterprise Edition, it is also necessary to call the Users::refreshTotal() method to update the user's case counters, so there is one less canceled/completed case and one more inbox case.

Note: As of ProcessMaker 3.1, the Users::refreshTotal() method is no longer available.

For example, a process is created to reopen selected cases which are canceled or completed. This process contains the following DynaForm:

The grid is associated with a grid variable named "casesList" and it contains the following grid fields:

• checkbox with ID 'reopen'
• textbox with ID 'caseNo' (disabled mode)
• textbox with ID 'process' (disabled mode)
• textbox with ID 'task' (disabled mode)
• textbox with ID 'user' (disabled mode)
• textbox with ID 'updated' (disabled mode)
• textbox with ID 'status' (disabled mode)
• hidden field with ID 'caseId'
• hidden field with ID 'index'
• hidden field with ID 'userId'

This grid is populated by the following trigger code which looks up all the cases with 'COMPLETED' or 'CANCELLED' status in the database and places information about those cases in the "casesList" grid. This trigger is executed before the DynaForm:

A second trigger is created which is set to fire after the DynaForm. Its code loops through the @=casesList grid and reopens each case which is marked by the user.

If using the Enterprise Edition, make sure to uncomment the code which instantiates the Users class and calls its refreshTotal() method, so the number of canceled, completed and inbox cases will be accurate for the user assigned the reopened case(s).

Note: As of ProcessMaker 3.1, the Users::refreshTotal() method is no longer available.

To see a sample process containing this code, download and import the process Reopen_Cases-1.pmx (right click on link and select "Save As".

Executing a Task a Variable Number of Times

There are two ways to execute a task a variable number of times in a process, but both methods have their drawbacks.

Repeating a Task with a Loop-Around

Use an exclusive gateway to create a loop-around for the same task in the process map so the task can be repeatedly executed.

In this example, the "Repeated Task" needs to be worked on by a different user of a group each time it executes. For that, set it to use Value Based Assignment, so that a different user can be designated with each pass through the task.

The "Repeated Task" needs to be executed once by every member of a group named "Audit Team" (which has a unique ID of "684661865572a1d7cde5603040620405"). The group "Audit Team" has 3 members.

Set a Trigger to fire in the "Initial Task" which will lookup the members of the "Audit Team". The Trigger creates:

1. A case variable named @%noRepeats to keep track of the number of times the task has been repeated.
2. An array named @=membersAuditTeam to hold the unique IDs of the members of the "Audit Team" group.
3. A case variable named @@currentAuditor to hold the unique ID of the user who is designated to work on the "Repeating Task".

Set the "Repeated Task" to use Value Based Assignment with the variable @@currentAuditor.

Set the exclusive gateway after "Repeated Task" to use the following conditions:

Finally, set the following Trigger to fire with each pass through the "Repeating Task", so that @%noRepeats will be incremented and @@currentAuditor will be set to the next user in the @=membersAuditTeam array.

When running the case, the "Repeated Task" will be redirected three times, each time to a different user group before being redirected to the "Final Task".

If a Task May Repeat Zero Times

If the "Repeating Task" needs to have the possibility of not being executed at all (for example, if there are zero members in the "Audit Team"), then an exclusive gateway needs to be added before the "Repeating Task" to skip it.

Then, conditions can be added to the first evaluation routing rule to either go to the Repeating Task or skip to the "Final Task". For example:

The conditions in the second evaluation routing rule will be the same as in the previous example.

Drawbacks

Repeating a task with a loop-around has several drawbacks:

1. The task will be executed serially, so that it can take a long time for each user to execute the task one by one.
2. If the repeating task contains a DynaForm, then each new user can change the values of the DynaForm fields with each loop, so the values from the first user might get overwritten by the second user, and the values of the second user might get overwritten by the values of the third user, etc.

A Variable Number of Parallel Tasks

The other way to repeat a variable number of tasks is to create a parallel tasks which will all execute at the same time. Create as many variable tasks as the maximum number of times that the task could possibly be executed.

Note: ProcessMaker includes a parallel marker for tasks in version 3.0.1.4 and later, so the following code example is only necessary if using a previous version of ProcessMaker.

For example, if each parallel task needs to be executed by a member of the "Audit Team", then create as many parallel tasks as the largest number of possible members of the "Audit Team".

Set each of the parallel tasks to use Value Based Assignment. "Parallel Task 1" uses variable @@userForTask1, "Parallel Task 2" uses variable @@userForTask2, "Parallel Task 3" uses variable @@userForTask3 and "Parallel Task 4" uses variable @@userForTask4.

Then, set a Trigger to fire in the "Initial Task" which determines the number of parallel tasks to execute and which users will be designated to work on each parallel task.

For example, the following Trigger fired during the "Initial Task" looks up the members of the "Audit Team" (which has a unique ID of "684661865572a1d7cde5603040620405") and assigns each member to a different parallel task:

Set the conditions in the Inclusive Gateway so that only as many parallel tasks are executed as the number of members in the "Audit Team":

Finally, set the steps for each of the parallel tasks. If needing each parallel task to execute the same steps, then keep the following caveats in mind:

• For DynaForm steps, create a separate DynaForm for each of the parallel tasks. If the same DynaForm is used in all the parallel tasks, then every user can overwrite the data entered by the other users.
  To create separate DynaForms for each parallel task, use the Save As option to create copies. Then go through the copies and rename all the DynaForm fields so they have different names.

• For Input Document steps, the same Input Document can be used for all the parallel tasks. Each auditor can add additional files to the existing Input Document. However, if none of the auditors should be able to see the Input Document files from the other auditors, then create a separate Input Document for each parallel task.
• For Output Document steps, the same Output Document can be used for all the parallel tasks as long as versioning is enabled, so each user doesn't overwrite the Output Documents of the other users.

Sending Grid Information via Email

If the information of a Grid is required to be sent via email follow the steps below:

1. Let's say that we need to send by email the information of a list of users adding in a grid, the id of the grid is GridName and the fields ids are FirstName and LastName respectively

Create a trigger with the following HTML code on which the structure of the grid will be created:

It is necessary to create a table structure with a $Grid variable, this variable will be defined to store all the HTML structure, on each line $Grid variable will be concatenated with a previous value to construct the table. On the first part the header of the grid is defined, also cases variables can be defined. As the example above some styles can be used.

On the second part, it is necessary to add a foreach sentence, since it is not possible to know how many rows will be created on the grid, so foreach will allow to go through each line of the grid to create it on the template.

2. Once the structure of the Grid is created, the PMFSendMessage function must be added to define the necessary parameters to send the email:

Since $Grid is an array it must be send on the last parameter of the function.

Grid will be the name of the variable which will be defined inside template.html, it means that this variable will contain all the grid structure stored at $Grid.

3. Finally create an HTML template named template.html with the following line:

Assign the trigger After Derivation or After Dynaform. Don't forget to configure email notifications to have mails sent successfully.

Create new case and change its status

When a new case is created, its status is automatically set to "DRAFT", so it doesn't appear in the list of cases under Home > Inbox. The Cases::updateCase() method can be used to change the status of the case from "DRAFT" to "TO_DO", so it will appear in the user's Inbox. If using the Enterprise Edition, it is also necessary to call the Users::refreshTotal() method to update the assigned user's case counters, so there is one less draft case and one more inbox case.

Note: As of ProcessMaker 3.1, the Users::refreshTotal() method is no longer available.

The following example creates a new case using the PMFNewCase() function and then changes its status to "TO_DO":

If using the Enterprise Edition version 3.0.X, then the number of To Do and Draft cases for each user needs to be adjusted after changing the status of a case. Use the following code to change the case counters for the user assigned to the new case instead of the above code:

Note: As of ProcessMaker 3.1, the Users::refreshTotal() method is no longer available.

Note that the above method should only be used if setting the status of a case to "TO_DO" or "DRAFT". if needing to change the case's status to "CANCELLED", "DELETED" or "PAUSED", then the corresponding PMFCancelCase(), cases::removeCase() or PMFPauseCase() functions should be used. To change the status to "COMPLETED", the PMFDerivateCase() function can be used to complete a final task in the process.

Create new case with a self service task

When a new case is started with the PMFNewCase() or PMFNewCaseImpersonate() functions (or the corresponding web services or REST endpoints), the case will be assigned to the specified user. This is a problem if the case needs to start with a task which has Self Service or Self Service Value Based Assignment, so it should not have an assigned user.

The workaround to this problem is to create a dummy task before the self service task in the process:

Then, after creating the new case, call the PMFDerivateCase() function, the routeCase() web service or the PUT /cases/{app_uid}/route-case REST endpoint to route the new case from the dummy task to the self service task. The case should then appear in the Home > Unassigned list, where any of the users who are in the assignment pool for the self service task can claim it.

Example with a Self Service task:

With a Self Service Value Based Assignment task

If a new case should begin with a Self Service Value Based Assignment task, then the variable which holds the assignee(s) to the task needs to be passed to the new case.

In this example, there is one process with the "Start case" task:

and another process with a "dummy task" and a "Self service task" which uses Self Service Value Based Assignment:

The "Start case" task contains a DynaForm with a dropdown box associated with the @@selfServiceAssignee variable. This dropdown is used to select the user or group to assign to the Self Service Value Based Assignment task:

In the properties of this dropdown box, the datasource is set to "array variable" and the data variable is set to @=aAvailableAssignees. This variable holds a array of the users and groups assigned to the "Self service task".

The following trigger code, which is fired before the DynaForm, populates the list of available users and groups in the dropdown box:

The trigger code retrieves the list of assigned users/groups from the USER_GROUP table in the database and places them in the @=aAvailableAssignees array to display in the dropdown. If the user or group's status is not set to 'ACTIVE', then it is not included in the list.

After the DynaForm, a second trigger is executed to create the new case:

The @@selfServiceAssignee variable is passed to the new case which is created with the PMFNewCase() function, so that the ID of the user/group selected in the dropdown box will assigned to the "Self service task" in the second process.

After creating the new case, the trigger code then calls PMFDerivateCase() to move the new case from the "dummy task" to the "Self service task". If an individual user was assigned to the task, then the trigger calls Cases::setCatchUser() to claim the case for that user. That way the user does not have to look under HOME > Unassigned to find the case and manually claim the case.

Finally, G::SendMessageText() is called to display a message at the top of the next screen to inform the user of the case number of the new case and who the case was assigned to.

In order for this example to work, set the "Self service task" to use the @@selfServiceAssignee variable in its "Assignment Rules" properties:

Make sure that all the users/groups which are assigned to the "Start Case" task in the first process are also assigned to the "dummy task" in the second task. This is necessary, because the logged-in user needs to have the rights to call PMFDerivateCase() and route paste the "dummy task".

To test this example, download and import the Start Case with self service process (right click and select "Save As").

Select the user for a Value Based Assignment task

Value Based Assignment can be used if needing to select a user to assign to task. This example shows how to populate a dropdown box in a DynaForm to select the user to assign to a task with Value Based Assignment. It also shows how to assign a user randomly from the pool of available users for a task.

The following process is used to complete a work order. The second task named "Do Work" uses Value Based Assignment. On the first pass through the "Do work" task, the user is chosen randomly from the pool of available users assigned to the task. In the third task named "Inspect work," a manager decides whether the work was done properly. If not, the manager can mark a checkbox to redo the "Do Work" task and can select a user from a dropdown box to assign to the task. Then the process will loop back to the "Do Work" task.

To implement this process, first create the following variables:

• A string variable named "userAssignedToWork" which will be the variable used for Value Based Assignment in the "Do Work" task.
• An array variable named "availableUsers" which will hold the list of available users in the assignment pool for the "Do Work" task.
• A boolean variable named "doWorkOver" for a checkbox which is marked to redo the "Do Work" task.

Second, right click on the "Do Work" task, and select Assignment Rules from its context menu. In the dialog box that opens, select Value Based Assignment and set its Variable for Value Based Assignment to @@userAssignedToWork.

Third, create the following DynaForm which the manager in the "Inspect Work" task will fill out if the "Do Work" task was not completed correctly in order to redo the task.

In this DynaForm, the "Do work over?" checkbox is associated with the "doWorkOver" variable. The "Assign work to" dropdown box is associated with the "userAssignedToWork" variable. In the dropdown's properties, the datasource is set to "array variable" and the data variable is @@availableUsers. Set this DynaForm as a step in the "Inspect Work" task.

Fourth, go to the process map and right click on the exclusive gateway and select Properties from its context menu. In its routing rules, set the following conditions:

If the "Do work over?" checkbox is marked, its @@doWorkOver_label variable will be set to "true"; otherwise it will be set to "false". In routing rules conditions, is recommended to use isset() to check whether the variable exists, just in case the user decided to use the Steps menu to skip the DynaForm, so the variable was not saved.

Fifth, create the following trigger to randomly assign a user to the "Do Work" task from the pool of available users:

The Derivation::getAllUsersFromAnyTask() method is called to get an array of the unique IDs of the users assigned to the "Do Work" task. Then, the rand() function is used to randomly select one of those users to assign to the "Do Work" task. Set this trigger to execute before assignment in the "Fill work order" task.

Sixth, create another trigger to populate the list of users in the "Assign task to" dropdown box:

This trigger calls Derivation::getAllUsersFromAnyTask() to get an array of the users and then loops through the list, copying the user's IDs and full name into the @=availableUsers array, which will populate the list in the dropdown box. Set this trigger to execute before the DynaForm in the "Inspect Work" task.

Finally, assign users to the different tasks in the process, so that cases can be run in the process.

To test this example, download and import the Loop Around process (right click and select "Save As").

Pausing Cases between Activities

The intermediate timer event is designed to pause a case between activities (tasks and subprocesses) in the process, but the date and time for this event is fixed and cannot be set dynamically. Instead, the PMFPauseCase() or Cases::pauseCase() functions can be used to pause a case. However, these functions immediately pause the case, rather than pausing them between activities. This trigger example shows how to call PMFPauseCase() between activities and dynamically set the datetime when the case will unpause.

In the following process, the case is paused between "Task 1" and "Task 2". In Task 1, there is a DynaForm where the user selects a datetime when the case should start "Task 2".

First, create two variables:

• A datetime variable named "pauseTillDate", which will set the datetime when the case will unpause.
• A datetime variable named "todayDate", which will set the minimum date in the date picker.

Second, create the following DynaForm with a datetime field associated with the "pauseTillDate" variable. In the datetime's properties, set its min date to @@todayDate. If needing to set the hours and minutes when the case will unpause, set its format to YYYY-MM-DD HH:mm.

Set this DynaForm as a step inside "Task 1".

Third, create the following trigger, which will set @@todayDate to today's date:

Set this trigger to execute before the DynaForm containing the datetime field.

Fourth, create another trigger which will call PMFPauseCase(). It uses Cases::LoadCase() to look up the user assigned to the next task in the process.

Set this trigger to execute after routing in "Task 1". At that point, "Task 2" will have already been created in the database, so that the case can be paused in the second task.

The steps and triggers in "Task 1" should have this placement:

Make sure to configure the server where ProcessMaker is installed to periodically execute the cron.php script, so that cases will be unpaused at the configured datetime. When a case is run, it will pause until the selected datetime before starting "Task 2". If the user does not select a datetime to pause the case, then it will pause indefinitely until the user assigned to "Task 2" manually unpauses the case.

To test this example, download and import the Pause Case process (right click and select "Save As").

Sending an email when a case is unpaused

The following example shows how to send an email to the assigned user of the current task when a case is unpaused. First, create a separate process that contains a script task which will be periodically executed.

Note that it is not possible to start a process with a script task, so the "dummy task" has to be created to start the process.

Right click on the intermediate timer event, and select Properties from its context menu. In the "Timer Event Properties" dialog box that appears, select the Wait for option and set the Minutes to "20".

Then, create the following email template named 'unpauseCase.html' which will be sent when the case is unpaused:

Then, create the following trigger in the same process:

Change 'admin@example.com' to match the email of the default account set under Admin > Settings > Email Servers.

This trigger uses executeQuery() to look up the cases which are ready to be unpaused in the APP_DELAY table in the database. For each case, the trigger uses the Cases::unpauseCase() method to pause the case. When the case is paused, its delegation index is incremented by 1. Then, details about the case are obtained with Cases::LoadCase(), Task::Load() and userInfo(). These details are stored in an array of variables that will be passed to the PMFSendMessage() function, which sends an email to the user assigned to the case.

Set this trigger to be executed by the script task. Right click on the script task and select Properties from its context menu. Then, select this trigger in the dropdown box. Then, assign a user to the "dummy task" and run a case in the process.

Finally, configure the ProcessMaker server to periodically execute the timereventcron.php script as a cron job in Linux/UNIX or a Scheduled Task in Windows. Make sure that timereventcron.php is executed before cron.php, because cron.php will also unpause cases so there won't be any cases to unpause by the above trigger if it is run after cron.php.

To test this process, download and install the Periodic_Script_Task-1.pmx process (right click and select "Save Link As").