Note that case variables only have scope when their case is open. To create global variables which can be accessed by any case, use this workaround .

Typing rules for Case Variables

When referencing a case variable within a trigger, take into account the following rules:

For example, this statement uses 3 case variables which are parsed as an integer, its original type and a string, respectively.

Where:

Type transformation of case variables only happens when the variable is an R-value, which means that it is what is on the right-hand side of an assignment statement and is what is assigned from :

If a case variable is a L-value or is what is assigned to , no type transformation happens. For example:

It is important to note that variable_name follows the PHP rules for variable names definition. That means a valid case variable name in ProcessMaker starts with a letter or underscore, followed by any number of letters, numbers, or underscores. Case variables are case sensitive, so @@myvar , @@MyVar and @@MYVAR are three different variables. If passing values between triggers and DynaForms, make sure that the case variable name in the trigger is spelled the same as the field name in the DynaForm. ProcessMaker case variables are stored separately from normal PHP variables, so a trigger with $myVar and @@myVar would have two different variables.

ProcessMaker retains the original value of case variables as normal PHP variables, so they not altered by using the different transformation rules. For instance:

ProcessMaker case variables can not be inserted into strings like normal PHP variables. The following statement will NOT work:

To insert case variables in a string, either reassign them to normal PHP variables and insert them:

Or use the dot operator (.) to concatenate strings with case variables:

Note: ProcessMaker does NOT support the following assignment:

System Variables in Triggers

In addition to case variables, triggers can also use system variables , which are predefined variables which have the same syntax as case variables and hold information about the current ProcessMaker system.

ProcessMaker has the following system variables:

Note: UID stands for "unique identification" which is a string of 32 hexadecimal characters to identify objects in ProcessMaker. To find the UIDs for processes, tasks, cases, users, groups, etc., see Consulting the ProcessMaker databases .

Operators

Operators in ProcessMaker triggers are handled like the PHP language.

Terminating Statements

A statement in a ProcessMaker trigger can extend for multiple lines. All statements should terminate with a ";" (semicolon) to indicate where the statement ends.

Examples

Creating Custom Triggers

To create a custom PHP trigger, open the list of triggers, by going to PROCESS > TRIGGER and click on the New link, to create a new trigger. Select Custom Trigger as the image below:

Then, the following editor will open:

Where:

On the text area field add the trigger code, it is possible to insert system or case variables by clicking on the @@ variable picker.

On the following example, the trigger created will obtain the user and date, and they will display in the Dynaform, in a field called TASK_DATE and USER_NAME respectively.

If you're running version 2.5.2 , when creating triggers, you will only need to fill out the name and description, and not the code anymore, this because a new enhancement was incorporated in the edition of triggers.

When editing it, this new editor, releases in an earlier version ( 2.5.1 ), will open in a new popup window.

As follows you will see its improvements:

Getting the function list

Available Version: 2.5.1

Usually, it is difficult to remember functions and sentences to be used in ProcessMaker. The trigger editor in version 2.5.1 and later has added a list of ProcessMaker functions and standard PHP elements to be inserted while a trigger is being edited. Press Ctrl + Space in the trigger editor, see function list and select one to insert:

Double click on one of the functions in the list to have it inserted in the trigger editor.

Moreover, if you remember the PM function you want to use, but not its parameters, look for it in the editor. For example, the parameters of the PMFSendMessage() function can be shown:

Press Ctrl + Space once more to list all parameters (required and not required) available for this specific function:

Double click on the parameters you will use to have the function added in the editor:

Syntax Highlighting

Available Version: 2.5.1

Version 2.5.1 and later includes the CodeMirror text editor which shows syntax highlighting when editing trigger code. Case and process Variables as well as conditions have their own color, which helps to identify any errors in the code.

CodeMirror text editor also shows the line numbers. In addition, it has automatic indentation to make code easier to read. Those improvements will help programmers to make their code understandable and easier to debug.

Trigger Wizard

ProcessMaker provides a user-friendly Trigger Wizard to easily create triggers using ProcessMaker functions (or functions provided by plugins) without doing any PHP programming. The Trigger Wizard is designed to help process designers who don't know the PHP syntax, but still want to be create triggers which call a single ProcessMaker function. For each function, the Wizard displays a dialog box to input each parameter for the function and enter a variable to store the return value from the function.

Creating a Trigger with the Wizard

Open the list of triggers, by going to DESIGNER > TRIGGER and click on the New link, to create a new trigger. Find the type of function that will be called by the new trigger, such as ProcessMaker Functions or Sugar CRM Functions and click on [+] to expand its list. Then, select the specific function to use from the list.

After selecting the function, a dialog box will appear to define the properties of the trigger and the parameters of the function to be called by the trigger.

A header describes the general purpose of the specific ProcessMaker function and provides a (More info) link where the function is described in the ProcessMaker wiki.

Details
In this section, define the properties of the new trigger:

Parameters
Enter the parameters for the specific function that will be called. For each parameter, enter a value which can be:

A new variable picker was added from version 2.5 , since a new WYSIWYG HTML Editor was also included.

If a string parameter needs to use a PHP variable such as $myVar , reference a PHP superglobal array such as $_SERVER['SERVER_ADDR'] , do operations with multiple variables such as @@FirstName . @@LastName , or make a function call such as getCurrentDate() , then edit the trigger's source code after using the Trigger Wizard.

Return value

After defining the properties the trigger, click on Save . Then, insert the new trigger into the process where it will be fired when running cases.

Editing Triggers Created by the Wizard

After a trigger has been created by the Trigger Wizard, it can be edited by going to PROCESS > TRIGGERS and clicking on the Edit link for the particular trigger. A dialog box will appear to redefine the properties of the trigger.

Enter new properties or parameters for the trigger and click on Save . To directly edit the source code for the trigger, click on the Edit Source Code link at the top, which will open the source code in a plain text editor.

After editing the source code, the trigger can no longer be edited with the graphical wizard interface in the future, so only use this option if necessary.

Copy/Import Triggers From a Process

Available Version: 2.5

Often sub-processes need the same triggers as the main process, or reuse a trigger used on a different process located at the same workspace, to avoid doing this manually. To reuse a trigger from a different process located in the same workspace, select the option to Copy/import Triggers from a process, then go to the Trigger Wizard, click on New < Import/Copy Trigger from a Process :

By clicking on this option, a new window will display with the following Trigger Information to be filled:

Where:

For example:

Copying a trigger from a Sub-process:

Click on Copy/Import and Save to have the trigger copied and added on the trigger list:

Inserting a Trigger in a Process

After creating a trigger, it can be inserted at various points in a process. Login to ProcessMaker as a user such as "admin" who has the PM_FACTORY permission in his/her role . Then, open a process for editing.

Firing Triggers Based on Conditions

Select a Trigger from the dropdown box of available Triggers. If only wanting the trigger to fire in certain situations, enter a condition that must evaluate to true in order for the trigger to be fired. Use the [@@] button to insert system and case variables in the condition. If left blank, the trigger will always fire. Then, click the Assign link to add the trigger.

Now the trigger should appear in the list of triggers to fire. Multiple triggers can be added to the list. The order which they fire can be changed by clicking on the Up and Down buttons.

In version 2.8.0 and later , a green check mark will appear for triggers which have defined conditions. This visual clue reminds process designers which triggers have defined conditions, which is helpful when trying to figure out why a trigger did not fire:

Debugging Triggers

When running cases, it is possible to see when triggers are executed and the value of system and case variables by turning on the ProcessMaker Debugger.

Enabling Debug Mode

There are two ways to enable Debug Mode, so the ProcessMaker Debugger will be displayed in a left sidebar while running cases for a particular process.

Login to ProcessMaker with a user such as "admin" who has the PM_FACTORY permission in his/her role . Then, go to the DESIGN menu. Right click on a process in the list and select the Énable Debug Mode option from the dropdown menu.

Debug Mode can also be enabled while editing a process. Right click on a blank area in the Process Map and select the option Edit Process from the menu.

In the Properties dialog box, mark the Debug checkbox:

Using the ProcessMaker Debugger

To use the ProcessMaker Debugger, run a case for a process which has enabled Debug Mode. The ProcessMaker Debugger will appear in a left-hand sidebar to view the system and case variables and see the code of the triggers that have just been executed.

The Variables tab shows the values of the system variables and the case variables for the currently open case. Each variable is displayed, along with its value. To see the content of long strings and arrays, click on a variable to see its value displayed in the box below.

The list of variables can be filtered by clicking on the buttons at the top:

Note: The box below to display variable contents doesn't automatically refresh its contents, so click on the variable again to refresh the contents of the box.

The Triggers tab shows which triggers have just executed and whether they executed before or after the last step or routing. To see a particular trigger's code, click on the trigger and its code will be displayed in the box below.

To see a trigger's code in a separate window, click on the Open in a New Window .

After each step, the Debugger will pause the case, so the variables and triggers can be examined in the Debugger. To continue running the case, click on the Continue button.

The Debugger will also pause after the task has been routed (derived), so the results of the triggers from before assignment, before derivation and after derivation can be examined.

Viewing Error Messages

If a fatal PHP error occurs in the trigger code when running a case, the case will stop and a PHP error message will be displayed in the cases frame:

If a PHP warning or non-fatal error (such as a syntax error) occurs while executing a trigger, the execution of the trigger will stop and a message will be displayed at the top of the cases frame. Nonetheless, the execution of the case will continue, so the use can work on the next step in the task. These are the only types of error messages whose line numbers correspond to the line numbers of the trigger code.

If Ext JS (which is a JavaScript framework used by ProcessMaker) detects an error, it will also display error messages in a dialog box:

All of these types of errors are immediately obvious to the user running the case, however, ProcessMaker exceptions will not be displayed to the user when running a case. When a ProcessMaker exception occurs, the system variable @@__ERROR__ is created to store its error message.

The easiest way to detect these types of errors is to turn on the ProcessMaker Debugger and check if __ERROR__ appears in the sidebar when running cases. If it appears, click on the __ERROR__ variable to see its content in the box below:

Examining Normal PHP Variables

It is often difficult to figure out what is the problem with trigger code, because the values of normal PHP variables can't be seen when running a case. If debugging code, it is recommended to assign normal PHP variables to case variables, so they can be seen with the ProcessMaker Debugger.

For example, if unable to figure out why a database query is failing, assign the result to a case variable so it can be seen in the Debugger:

If needing even more detailed information about a variable, the contents of variables can be displayed with var_dump() wrapped in <pre> tags:

If needing to force trigger execution to stop at a certain point, so variables can be displayed, then call die() . Be aware, however, that die() will stop the execution of the case from continuing onto the next step and will stop DynaForm data from being saved if called after a DynaForm step.

Error Management

Error Management for Processes in Production

Activating the ProcessMaker Debugger is a good way to detect errors when designing processes, however, it is not recommended when running cases in production. Not only is the debugger distracting for normal users, it also creates a potential security hole if users can see data entered by other users in the case.

Most of the time, bugs will be detected when designing the process, but some types of bugs are caused by unexpected user input or unanticipated circumstances such as a condition which contains a variable which didn't get defined because a step gets skipped. The most common source of these errors is unexpected user input which causes problems when querying the database in a dependent field or when a trigger calls executeQuery() .

For example: