3.2 - 3.8 - ProcessMaker Functions - Dynaform and Field Functions

Dynaform and Field Functions

PMFDynaFormFields()

PMFDynaFormFields() retrieves all the properties of each field in a Dynaform. If the unique ID and delegation index of a case is specified, it will also retrieve the entered value of each field and its label. Note that the label is the same as the value for textboxes and textareas, but it is the displayed text of a selected option in a dropdown box, suggest box, radio button, checkbox and checkgroup.

Parameters:

• string dynaformUID: The unique ID of the Dynaform where the fields are located.
• string caseUID: Optional. The unique ID of a case. If specified, then the values and labels of that case will be inserted into the properties of the Dynaform fields. Make sure that the specified case and the specified Dynaform belong to the same process. The unique ID of a case can be found in the following ways:
  • Use the @@APPLICATION system variable to get the unique ID of the current case.
  • Use the PMFCaseList(), WSCaseList() or the caseList() web service.
  • Use executeQuery() to look up the case UID in the wf_<WORKSPACE>.APPLICATION.APP_UID field in the database.
• int delIndex: Optional. The delegation index of the case. If specified, then values and labels of that case will be inserted into the properties of the Dynaform fields. The delegation index starts counting at 1 for the first task in the case, 2 for the second task, 3 for the third task, etc. It can be found in the following ways:
  • Use the system variable @%INDEX to get the delegation index of the current case.
  • Use the PMFCaseList(), WSCaseList() or the caseList() web service.
  • Use executeQuery() to look up the delegation index in the wf_<WORKSPACE>.APP_CACHE_VIEW.DEL_INDEX field WHERE DEL_THREAD_STATUS='OPEN'.

Return Value:

An associative array of information about each field contained in the Dynaform specified. The return value will depend on how many and what kind of fields are inside the Dynaform.

Example:

First, create a simple Dynaform with the same fields as the Dynaform in the image below:

Second, copy the number of the Dynaform:

Third, create the following trigger with the number of the Dynaform:

The variable @@Afields will obtain all the information about each field contained in the Dynaform. The return value can be seen using the Processmaker Debugger:

PMFGetDynaformUID()

PMFGetDynaformUID() retrieves the unique ID of a Dynaform using the Dynaform name and, if required, the unique ID of the process.

Parameters:

• string dynaformName: The name of the Dynaform.
• string processId: Optional parameter. 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 PRO_UID FROM PROCESS WHERE PRO_TITLE = 'Purchase Request Form'

Return value:

• string: The function returns the unique ID of the Dynaform.

Example:

@@dynUID = PMFGetDynaformUID("Purchase Request Form",'75150592456d5efe4848088021942802');

The returned value stored in @@dynUID will be '81917311556d5f0d0622012054540345'.

PMFRemoveMask()

The PMFRemoveMask() function removes the mask of a currency field by deleting the thousands separator (which is a "." (period) or "," (comma) and the currency symbol, such as "$", "€", "£" or "¥". Call this function before using a currency field in a mathematical calculation that requires a number rather than a string.

string PMFRemoveMask(string fields, string separator = '.', string currency='')

Parameters:

• string field: Value to be stripped of thousands separators and currency symbols.
• string separator: Optional. The thousands separator, which by default is "," (comma). In most European and Latin American countries, the thousands separator is "." (a period).
• string currency: Optional. The currency symbol. This parameter is set to an empty string by default, so if the parameter is not set no currency symbol will be removed.

Return Value

A string with the the currency and thousands separator removed.

Note: PMFRemoveMask() returns a string. In most cases this is not a problem, because PHP will automatically convert the string into a number if it is used with a mathematical operator (+, -, *, /, %, etc.) or compared (==, !=, >, >=, < or <=) with a number. Nonetheless, it may be a good idea to convert the string into a real number using floatval(), or into an integer using the intval() function to avoid potential problems.

Example in a trigger:

Use the PMFRemoveMask() function to delete the mask of a value introduced in a currency field named "Amount". Then use the is_numeric() function to check whether it can be converted into a number. If so, then convert it to a real number and then subtract 10% from the amount for a discount. If not a valid number, then use the G:SendMessageText() function to display a warning message to the user on the next screen:

$amount = PMFRemoveMask(@=Amount, ",", "$");
if (is_numeric($amount) {
    $amount = floatval($amount);
    @=Discount = $amount - $amount * 0.10;
}
else { //if not a valid number, then display warning message
   $g = new G();
  $g->SendMessageText(@=Amount . " is not a valid amount.", "WARNING");
}

For instance, if the value of @=Amount is "$5,000.00", then it will be converted into "5000.00" and floatval() will convert it into 5000.00 (a real number). Notice that the comma (,) and the dollar sign ($) were removed from the string.

Note: Case variables that are passed as the first parameter of PMFRemoveMask() should be referenced as @@field-name or @=field-name, so that they are maintained as text. Do NOT use @#field-name or @%field-name, since PHP will try to convert the value to a number, which probably will not work correctly, depending on the mask.

Example in a condition:

Depending on the value introduced in a field, the following condition is used to decide whether the workflow moves to subsequent task(s):

(PMFRemoveMask(@=Amount, ",", "$") >= 100 and PMFRemoveMask(@=Amount, ".", "$") <= 10000)

This condition can be used inside an evaluation routing rule:



PMFgetLabelOption()

PMFgetLabelOption() returns the label of a specified option from a dropdown box, listbox, checkgroup or radiogroup.

Warning: Note that this function cannot be used with fields that have a dependent SQL query set.

string PMFgetLabelOption(string processUID, string dynaformUID, string fieldName, string optionUID)

Parameters:

• string processUID: The unique ID of the process that contains the field. To use the current process, use the system variable @@PROCESS.
• string dynaformUID: The unique ID of the Dynaform where the field is located.
• string fieldName: The field name of the dropdown box, checkbox group or radiogroup from the specified Dynaform.
• string optionUID: The value (i.e., ID) of the option from the fieldName.

Return Value:

A string holding the label of the specified option or NULL if the specified option does not exist.

Example:

@@countries_lab = PMFgetLabelOption(@@PROCESS, '6962405664a55ed3b36b168077366134', 'countries', @@countries);

Where:


• "6962405664a55ed3b36b168077366134": is the UID of the Dynaform that holds the dropdown box.
• "countries": is the name of the field whose values are displayed as options in the dropdown box.
• "@@countries": is a variable that holds the ID of the option that has been selected in the dropdown box.

To find the label from the selected option in a dropdown box, it is not necessary to use PMFgetLabelOption().

Dropdown boxes have a new attribute called "saveLabel". When set to "1", it permits the value of a label for a selected option to be saved automatically in a variable with the same name as the original variable, but with "_label" added to the end of the variable name. For instance, if trying to find the label of the selected option in the "countries" dropdown box, it can be found in the "@@countries_label" variable.