3.1 - Variables

Overview

Case variables are variables which are created inside a project and stored exclusively for each case. They are automatically created when a new case is initiated and can be used in any of the objects in a process. Case variables can be defined in the process designer, and can then be used to populate fields in DynaForms and throughout the process in Output Documents, triggers and email templates.

Defining Variables

Warning: Before creating a variable, read the rules in the Naming Variables section to name it properly.

To define case variables, open the project in which they will be used. In the main toolbox, click on the + icon next to the "Variable" option.

Fill out information about the new variable in the modal window that opens:

Warning: ProcessMaker does NOT support variables created with characters from Arabic, Hindi, Japanese or other languages that do not use the Latin alphabet.

1. Variable Name: Required. Variables have a unique name without spaces between 3 and 64 characters long, which ProcessMaker uses to identify the variable. ProcessMaker designers can use the variable name in DynaForm fields, email and Output Documents templates, trigger code, etc. Normal PHP variable naming rules apply, so the name is case sensitive and it must start with a letter or underscore and can only contain characters which are letters, numbers and underscores. Symbols and spaces are not allowed.
   
   If trying to add a variable that doesn't have a valid name, the following error message will appear:

   

   Note: A variable name must match the regular expression: ^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*

2. Variable Type: Required. Select the data type of the new variable. The data types supported by ProcessMaker version 3 are:
   • String Accepts characters of any type, including letters, numbers, symbols and spaces. String variables can be used to populate textboxes, textareas, suggest boxes, dropdown boxes, radio buttons and hidden fields. For example, a string variable can be used to store a description:

     

   • Integer: Accepts only whole numbers between -2147483648 and 2147483647. This whole number can be positive, negative, or zero. It does not accept fractions. Integers are mainly used to populate textboxes, but they can also be used for other types of fields such as dropdowns, checkboxes, and radiogroups which store the selected key as an integer.
   • Float: A floating-point variable accepts real numbers with a decimal point, so it can accept fractions. It is a 4 byte floating-point number between -3.402823466E+38 and 3.402823466E+38. Numbers with 9 or more decimals will be rounded to the nearest integer. For instance, if the number 0.999999999 is entered, it will be rounded to 1.0000000. It is recommended to only use floats with textbox fields in DynaForms.

     

   • Boolean: Accepts only values of TRUE or FALSE to represent boolean logic. Any other values will be converted to TRUE or FALSE. All numbers except 0 (zero) and all strings except empty strings are considered TRUE. It is recommended to use these variables with checkboxes, dropdowns or radio buttons which only allow a binary choice (such as Yes/No, On/Off or Approve/Disapprove).

     

   • Datetime: Stores a date or datetime in the format "YYYY-MM-DD" or "YYYY-MM-DD HH:MM:SS". For example, the last second of the year 2015 is: "2015-12-31 23:59:59".

     

   • Grid: This type of variable is used to store Grid controls in DynaForms. ProcessMaker stores grids as a numbered array of associative arrays, which is the same format used when storing the results of database queries, so that grids can be populated with a database query.

     

     Note: This type of variable can also be related to the Subform's "Grid Store" property.

   • Array: This type of variable stores a collection of values. The values can be of different data types. In ProcessMaker, array variables can only be used by checkgroup controls.

     

   • File: Variable to store the file(s) selected in a file control. An Input Document can also be associated with a file variable. When defining an Input Document, a file variable can be selected to hold its contents, so that the Input Document can be accessed through a file control in a DynaForm or as a variable in a Trigger. Define the maximum file size, the destination path and allowed file extensions of the uploaded files in the Input Document. The file variable can then be associated with an existing Input Document.
     
     To use a file variable, first create an Input Document. Then, create the file variable and associate it with the existing Input Document. Finally, create a DynaForm with a file control and associate the file variable with that file control. When a file variable which is associated with an Input Document is used in a file control, then the properties in the control will be disabled, because those properties have already been set in the Input Document properties.

     

   • Multiple File: Variable to store multiple files selected in a Multiple File Uploader control. This variable can be used only with this control.
     

     

3. Database Connection: By default, this field is set to "PM Database", which is the wf_WORKSPACE database for the current workspace, which by default is named wf_workflow. If there are other Database Connections in the project, they can be selected in the dropdown menu.
4. SQL: A database query can be used to set the initial value of a variable associated with a textbox, textarea or hidden field or to populate the list of options in dropdown boxes, suggest boxes, radio buttons or checkgroups. Enter an SQL SELECT statement to populate the variable. Note that this statement is the default for controls which are associated with the variable, but this statement can be modified in the definition of each control. Do NOT include the name of the database in the query, since the query will be executed in the selected Database Connection (3). The SQL query is executed when a DynaForm is displayed which contains a control associated with the variable. If the SQL query contains a reference to an independent field (@@fieldId or @#fieldId), then it will be executed every time the value of the independent field is changed by the user.
   
   If populating a textbox, textarea or hidden field, then the control will be set to the value in the first field in the first record returned by the database query. If populating the list of options in a dropdown box, suggest box, radio button, checkgroup, then the first field will be the key and the second field will be the label of each option. These options from the SQL query will be added in the list after the fixed options.
   
   Note: If querying a MySQL database, remember that table and field names are case sensitive by default in Linux/UNIX systems, but case insensitive in Windows systems (although this can be changed with the lower_case_table_names system setting). For portability of processes between Windows and Linux/UNIX servers, it is recommended to use table and field names in UPPERCASE when querying ProcessMaker databases.
5. Define Accepted Variable Values. A list of accepted options can be added to string, integer, float, boolean and array variables. These options will be displayed to the user when the variable is associated with a dropdown box, radio button, suggest box, checkgroup in a DynaForm. Check this option and a new section will be displayed below where options can be added with key (value) and label pairs. These options will be added first to the list, before any options which are added by the SQL query. Note that this is the default list of options and it can be modified in the definition of each control which is associated with the variable.

   

   • a. Key. Required. The key (value) must be unique for each option since it acts as a unique identifier, so that no other option can have the same key. It may not contain any spaces. Note that the keys are stored as strings, so "3.10" is not the same key as "3.1".
   • b. Label. The label is the text which to displayed to users when the option is shown in a DynaForm.
   • c. Create. Click on this button to add a new option to the list.
   • d. List of the options already added to the variable. In this list the key (value) of the option and its label are shown.
     

     The variable values of this list can be drag and drop to modify the order.

     

   • e. Edit. Click on this button to edit the key or the value of the variable option.
   • f. Delete. Click on this button to delete the option of the variable.
   • g. Pagination Control. Use this control to navigate through the pages of options. Each page lists up to 5 options.

Boolean variables have options for the TRUE and FALSE keys. The label for each of these keys can be configured. Boolean variables can only be used with dropdown box, radio button and checkbox controls in DynaForms.

After filling out the information about the new variable, click on "Save" to add it to the list of available variables or "Cancel" to discard any changes.

Note: All variables for a case are stored in the MEDIUMTEXT field wf_<WORKSPACE>.APPLICATION.APP_DATA in the database, which holds a maximum of 16,777,213 bytes, so that the maximum number of characters in a string is determined by the size of that field, but can also be limited by the Size property of textboxes in DynaForms and by the post_max_size setting in the php.ini configuration file.

_label Variables

When a case variable is created, a second variable with a name based on the name of the case variable and the suffix _label is automatically created. For instance, if the new variable is named "phone", the second variable will be named "phone_label".

Warning: Avoid creating variables with a "_label" suffix in their name, it may lead to possible conflicts with variables created by the ProcessMaker application.

A _label variable is used to store the label of the variable stored in the @@variable related to a Dynaform control. For example: for a dropdown, the label of the selected option is saved as a variable with the same name as the case variable assigned to the dropdown, but with a "_label" suffix. If a dropdown box is named "MyDropdown", then the value of the selected option would be stored in the case variable @@MyDropdown, and the label of the selected option would be stored in the @@MyDropdown_label variable.

In the case of textboxes, textareas or suggest boxes, the same value typed in by the user is stored in the case variable, as well as in the _label variable.

The _label variable values are stored in the wf_<WORKSPACE>.APPLICATION.APP_DATA field in the ProcessMaker database.

Managing Variables

To manage the list of variables and create new ones, click on the "Variables" option in the main toolbox.

A list of variables will appear along with options to add new variables and edit or delete the existing variables.

• Name: This column lists the name of the variable. By default the variables are listed by their names in ascending alphabetical order. Click on the down triangle icon in the column header to switch to descending alphabetical order.
• Type: This column lists the data type of the variable.
• Edit: Click on this button to edit the variable's name or its type.
• Delete: Click on this button to delete the variable. When the confirmation message appears, click on "Yes" to delete the variable. Variables which are already being used to populate a DynaForm field can not be deleted. First, they have to be removed from the DynaForm, before deleting them. Note that ProcessMaker doesn't check whether a variable is used in trigger code before deleting it.

The variables are listed 10 at a time. To see the next page click on >, and to see the previous page click on <. To see other pages of variables, click on the page's number in the pagination control below the list.

To filter the list of variables, enter text in the search box in the upper left-hand corner. The search is case insensitive any where in the variable names or in their types.

Adding Variables in a DynaForm

After creating variables, they can to be associated with a control field in a DynaForm. To associate variables with fields in a DynaForm, check this documentation to learn how to do it.

Creating Variables inside the DynaForm Designer

Variables can also be created inside the DynaForm Designer, when dragging and dropping a control a new window will automatically appear.This window will be the "Create/Select" window and it has been added to aggregate functionality and behavior to the variables.

This new window will have two radio buttons offering two options which are: "Create variable" (creates a variable directly from this window) or "Select variable" (selects an existing process variable).

The "Create variable" option will allow the immediate creation of a variable by firstly adding a "Variable Name", for this example the variable will be "name".

Click the options "Settings" which is underlined and more options will be displayed.

The "Settings" available for the creation of variables are the following:

The "Type" setting is a dropdown which allows to choose the type of variable that will be used.This depends solely on the control chosen so the type of variable will change. In case is a "Textbox" control (like in the example below) the type of variable available will be "String", "Float" and "Integer". Try adding a "Datetime" control and the type of variable available will be only "datetime".

The "Database Connection" setting displays a connections already established with a Database or if empty create a new one. Read more about Database Connection on this section

The "Sql" setting adds a query to give more functionality to the control by clicking on the underlined ellipsis as seen in the image. For more information read this section

An "SQL Editor" will open where queries can be added.

Finally, the "Options" setting shows, edits and/or adds options set of the control that may be related to a variable or not. Check this section for more information.

If an existing variable wants to be added to the control simply click on the "Select variable" radio button.

All process variables will be displayed and one of them can be chosen for the control.