Manage Calculated Properties that perform calculations in your Screens.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Add a Calculated Property to a Screen.
Your user account or group membership must have the following permissions to add a Calculated Property for a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add a Calculated Property for a Screen:
Open the Screen in which to add a Calculated Property. The Screen is in Design mode.
View the Calculated Properties for that Screen. The Calculated Properties screen displays all Calculated Properties configured for this Screen. If no Calculated Properties have been configured for this Screen, No Data Available displays.
Click the +Property button. The Calculated Properties screen displays settings to configure a Property.
In the Property Name setting, enter the name of the Calculated Property. This Calculated Property name displays both in the Calculated Properties screen and in the JSON data model when previewing the Screen. Calculated Properties are case-sensitive. See Calculated Property Best Practices. This is a required setting.
In the Description setting, enter the description of the Calculated Property. This is a required setting.
Above the Formula setting, select one of the following ways to determine how the Calculated Property determines its value:
Follow these guidelines to reference Screen control or Magic Variable values:
Screen control value:
Reference a Screen control's value by referencing that control's Variable Value setting. Example: return this.FullName
when FullName
is the Variable Value setting value for the control to reference its value when the Calculated Property runs.
Magic Variable value:
Reference a Magic Variable's value. ProcessMaker Platform uses a set of Magic Variables that become part of the JSON data model for all Requests. ProcessMaker Platform uses these Magic Variables to store user, Process, and Request related data for all Requests. During an in-progress Request, these Magic Variables are updated. All Magic Variables are preceded by an underscore (_
) character in the JSON data model. Reference the Magic Variable after the this.
keyword. Example: return this._user.fullname
to reference the user's full name from the in-progress Request. See Magic Variable Descriptions. Note that there is no Magic Variable that stores the user that starts a Request. To address this, use a Calculated Property to reference the _user.fullname
Magic Variable's value in the Screen referenced in the first Task element of a Process; since many Processes are designed such that the Request starter is the user assigned the first Task in a Request, this is a helpful way of storing who the Request starter is. This Calculated Property stores this Magic Variable's value, which you may reference elsewhere.
In the Formula setting, enter the mathematical calculation/JavaScript that determines the Calculated Property value. This is a required setting.
Click Save. The Property displays in the Calculated Properties screen. The following message displays: Property Saved.
Ensure to save your Screen. The Calculated Property is not added to your Screen until you save it. Doing so will save your work if your session expires.
Mathematical calculation: Click the Formula iconto enter the value, mathematical calculation, or formula that calculates the Calculated Property. The Formula icon is selected by default.
JavaScript:
Click the JavaScript iconto calculate the Calculated Property using valid JavaScript. By calculating the Calculated Property using JavaScript, you can reference the values for Screen controls and Magic Variables. Ensure to use valid JavaScript to calculate the Calculated Property by using a return
statement to return the result of an expression (the value). Furthermore, ensure to use the this.
JavaScript keyword preceding the Screen control/Magic Variable reference. See the examples below.
Understand how to use Calculated Properties in your Screens.
Use Calculated Properties to easily design formulas that perform calculations and solve problems within the context of a Screen. The output of a Calculated Property is automatically generated, read-only, and is available immediately in the Request data model. Advanced JavaScript developers can use Calculated Properties to do more advanced data manipulations.
Use Calculated Properties to add more context to your Screen display. A Request should never trust any data that originates from the client side, and trusted calculations should always be performed within a Request in a Script Task element.
Calculated Properties have the following attributes:
Calculated Properties can only be used within and only affect the Screen to which the Calculated Property is added.
Calculated Properties are generated values that cannot be edited after calculation.
The name of a Calculated Property is case sensitive. For example, netCost
and NetCost
are two distinct names for Calculated Properties.
Below are a few uses for Calculated Properties that can be calculated mathematically or through JavaScript:
Perform simple mathematics. Example: 1+1
Calculate the final cost of a purchase based on a sales tax. Example: $60
(item cost) x .075
(sales tax)
Calculate the minimum credit card payment. Example: $1000
(amount owed) x .03
(interest rate)
Reference the Screen control values for a Property using their Variable Name setting values. For example, to determine the cost for a number of items in a Screen for a purchase request form that uses a Line Input control with a Variable Name setting of units
to indicate how many items to purchase, and price
is the amount per unit, use the following calculation in a Property:
units * price
Calculated Properties display as the second key-value pair of the Screen's JSON data model from the Data Preview panel when previewing that Screen.
Follow best practices when using Calculated Properties.
View the Calculated Properties for a Screen.
The following information displays about each Calculated Property:
Property name: The Property Name column displays the name of the Calculated Property.
Description: The Description column displays the description of the Calculated Property.
See the permissions or ask your Administrator for assistance.
Follow these steps to view the for a:
the Screen in which to view its Calculated Properties. The Screen is in .
Click the Calcs button. The Screen is in mode. The Calculated Properties screen displays all Calculated Properties configured for this Screen. If no Calculated Properties have been configured for this Screen, No Data Available displays.
Follow best practice guidelines and considerations when using Calculated Properties.
Follow these best practices and considerations when using Calculated Properties in Screens:
Calculated Properties are not designed to modify the current Screen control value(s). Calculated Properties read the value(s) from a specified Screen control via its Variable Name setting to calculate a result.
When designing a Calculated Properties, do not use the value from a Screen control which, in turn, calculates that property. Such design is circularly referencing the control from which to calculate its value.
Calculated Properties are not designed for a user to modify a Calculated Property via a Screen control.
When referencing a Calculated Property in a Screen, use its name in the exact case as defined since a Calculated Property's name is case sensitive. For example, netCost
and NetCost
are two distinct names for Calculated Properties.
Calculated Properties are not designed to introduce additional JavaScript functionality: doing so can cause instability in that Screen. ProcessMaker Platform does not support Screens that have additional JavaScript functionality within them.
Do not use third-party libraries within Calculated Properties such as jQuery or moment.js, as these libraries may be updated in and/or removed in ProcessMaker Platform. ProcessMaker Platform does not support Screens that use third-party libraries within them.
Do not reference one Calculated Property within another, such as referencing this.myCalcProp
in a Calculated Property named myCalcProp
: doing so causes a circular reference which degrades the performance of the Screen or may cause the Screen to stop functioning entirely.
If using a Calculated Property in a nested Screen that requires the value from its hosting Screen, then do not use the same Request variable in the nested Screen’s Calculated Property as that used in the hosting Screen.
Calculated Properties are generated values that cannot be edited after calculation.
Edit a Calculated Property for a Screen.
Your user account or group membership must have the following permissions to edit a Calculated Property for a Screen:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Avoid performance issues and follow best-use guidelines by following best practices.
Follow these steps to edit a Calculated Property for a Screen:
Open the Screen in which to add a Calculated Property. The Screen is in Design mode.
Edit the following settings about the Calculated Property as necessary:
In the Property Name setting, edit the name of the Calculated Property. This Calculated Property name displays both in the Calculated Properties screen and in the JSON data model when previewing the Screen. Calculated Properties are case-sensitive. See Calculated Property Best Practices. This is a required setting.
In the Description setting, edit the description of the Calculated Property. This is a required setting.
Above the Formula setting, select one of the following ways to determine how the Calculated Property determines its value:
Screen control value:
Reference a Screen control's value by referencing that control's Variable Name setting to use it in a mathematical calculation. Example to calculate the total cost of a purchase: NetCost
+ ( NetCost
* (SalesTaxRate
/100)) when NetCost
and SalesTaxRate
are the Variable Name setting values for the two controls storing the net cost for a purchase prior to sales tax and the local sales tax rate, respectively.
Magic Variable value:
Reference a Magic Variable's value. ProcessMaker Platform uses a set of Magic Variables that become part of the JSON data model for all Requests. ProcessMaker Platform uses these Magic Variables to store user, Process, and Request related data for all Requests. During an in-progress Request, these Magic Variables are updated. An underscore (_
) character precedes all Magic Variables in the JSON data model. Example to get the ID for the user completing the current Task in that Request: _user.id
.
Follow these guidelines to reference Screen control or Magic Variable values:
Screen control value:
Reference a Screen control's value by referencing that control's Variable Value setting. Example: return this.FullName
when FullName
is the Variable Value setting value for the control to reference its value when the Calculated Property runs.
Magic Variable value:
Reference a Magic Variable's value as described above for mathematical calculations. Reference the Magic Variable after the this.
keyword when using JavaScript as the input method. Example: return this._user.fullname
to reference the user's full name from the in-progress Request. See Magic Variable Descriptions.
In the Formula setting, edit the mathematical calculation/JavaScript that determines the Calculated Property value. This is a required setting.
Click Save. The Property displays in the Calculated Properties screen. The following message displays: Property Saved.
Ensure to save your Screen. The Calculated Property is not edited until you save it. Doing so will save your work if your session expires.
Delete a Calculated Property from a Screen.
Deleting a Calculated Property from a Screen cannot be undone.
Follow these steps to delete a Calculated Property from a Screen:
View the Calculated Properties for that Screen. The Computer Properties screen displays all Calculated Properties for this Screen.
Click the Edit iconfor the Calculated Property to edit. The Calculated Properties screen displays that Calculated Property's name, description, and how its value is determined.
Mathematical calculation: Click the Formula iconto enter the value, mathematical calculation, or formula that calculates the Calculated Property. The Formula icon is selected by default. Follow these guidelines to reference Screen control or Magic Variable values:
JavaScript:
Click the JavaScript iconto calculate the Calculated Property using valid JavaScript. By calculating the Calculated Property using JavaScript, you can reference the values for Screen controls and Magic Variables. Ensure to use valid JavaScript to calculate the Calculated Property by using a return
statement to return the result of an expression (the value). Furthermore, ensure to use the this.
JavaScript keyword preceding the Screen control/Magic Variable reference. See the examples below.
See the permissions or ask your Administrator for assistance.
the Screen in which to delete a Calculated Property. The Screen is in .
Click the Calcs button. The Calculated Properties screen displays all Calculated Properties for this Screen.
Click the Delete icon for the Calculated Property to delete. The Calculated Property is deleted, and the following message displays: Property deleted.