Calculated Properties

Manage Calculated Properties that perform calculations in your Screens.

Plan Availability:

What are Calculated Properties?

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

Permissions

Your user account or group membership must have the following permissions to view the Calculated Properties 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 view the Calculated Properties for a Screen:

1. Open the Screen in which to view its Calculated Properties. The Screen is in Design mode.

2. Click the Calcs button . The Screen is in Calculated Properties 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.

Calculated Properties screen in Calculated Properties mode

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.

Add a Calculated Property

Permissions

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:

1. View the Calculated Properties for a 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.

2. Click the +Property button. The Calculated Properties screen displays settings to configure a Property.

   

   Calculated Properties screen from which to add a new Calculated Property
3. 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.

4. In the Description setting, enter the description of the Calculated Property. This is a required setting.

5. Above the Formula setting, select one of the following ways to determine how the Calculated Property determines its value:

   • Mathematical calculation: Click the Formula icon to enter the value, mathematical calculation, or formula that calculates the Calculated Property. The Formula icon is selected by default.
   • JavaScript: Click the JavaScript icon to 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.

     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. 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:

       ProcessMaker Platform uses a set of Magic Variables that become part of the JSON data model for all Requests, and are updates during a Request. These Magic Variables are used to store user, Process, and Request related data for all Requests. All Magic Variables are preceded by an underscore (_) character in the JSON data model. 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 who 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.

6. In the Formula setting, enter the mathematical calculation/JavaScript that determines the Calculated Property value. This is a required setting.

7. 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.

Calculated Properties screen with a new Calculated Property

Edit a Calculated Property for a Screen

Permissions

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.

Follow these steps to edit a Calculated Property for a Screen:

1. View the Calculated Properties for a Screen.

2. Click the Edit icon for the Calculated Property to edit. The Calculated Properties screen displays that Calculated Property's name, description, and how its value is determined.

   

   Calculated Properties screen from which to edit a Calculated Property
3. Edit the settings as necessary and click Save.

Delete a Calculated Property

Permissions

Your user account or group membership must have the following permissions to delete a Calculated Property from a Screen:

• Screens: Edit Screens

• Screens: View Screens

See the Screens permissions or ask your Administrator for assistance.

Deleting a Calculated Property from a Screen cannot be undone.

Follow these steps to delete a Calculated Property from a Screen:

1. Open the Screen in which to delete a Calculated Property. The Screen is in Design mode.

2. Click the Calcs button . The Calculated Properties screen displays all Calculated Properties for this Screen.
3. Click the Delete icon for the Calculated Property to delete. The Calculated Property is deleted, and the following message displays: Property deleted.