Calculated Properties
Manage Calculated Properties that perform calculations in your Screens.
Use Calculated Properties (or Calcs) to easily design formulas that perform calculations and solve problems within the context of a Screen. JavaScript developers can use Calculated Properties to do advanced data manipulations. The output of a Calculated Property is automatically generated and is available immediately in the Request data model.
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 key features:
Calculated Properties can only be used within the Screen they are added to and only affect that specific Screen.
Calculated Properties are generated values that cannot be edited after calculation.
The name of a Calculated Property is case sensitive. For example,
netCost
andNetCost
are two distinct Calculated Properties.
What new in Summer 2024
Organize Calculated Properties easily with drag-and-drop functionality.
Temporarily disable specific Calculated Properties when necessary.
Access detailed logs to troubleshoot runtime errors with precision.
Enjoy expanded editing space in the editor, enhancing your ability to work with Calculated Properties.
Use Cases
Here are a few uses for Calculated Properties that can be calculated mathematically or through JavaScript:
Perform mathematical calculations. Example:
sqrt(350/25)*0.5
Calculate the final cost of a purchase based on a sales tax. Example:
60(item cost)*.075 (sales tax)
Calculate the minimum credit card payment. Example:
1000(amount owed)*.03(interest rate)
To reference Screen controls in a Calculated Property, use their Variable Name setting. For example, to determine the cost for a number of items in a Screen that uses a Line Input controls with a variable name units
and price
, 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.
View Calculated Properties for a Screen
Follow these steps to view the Calculated Properties for a Screen:
Open a Screen for editing. The Screen will open in Design mode.
The following information displays about each Calculated Property:
Property name: The Property Name column displays the name of the Calculated Property.
Type: The Type column indicates whether the property uses a formula or JavaScript.
Add a Calculated Property
Follow these steps to add a Calculated Property for a Screen:
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. This is a required setting.
In the Description setting, enter the description to explain the purpose of the Calculated Property. This is a required setting.
Click Save to save the configuration.
Best Practices and Examples
Using Formulas
Use formulas to quickly apply mathematical calculations. For example, the following formula calculates the total cost of a purchase:
Price + ( Price * (SalesTaxRate/100))
where Price
and SalesTaxRate
are the Variable Names for two Screen controls.
Using JavaScript
Use JavaScript for more complex calculations or small snippets of code.
For example, use the following code to obtain the current date for a control
let currentDate = new Date().toDateString(); return currentDate;
Use a
return
statement to return the result of an expression. For example,return TotalPrice
Ensure to use
this
JavaScript keyword when referencing Screen controls. For example: usethis.email
,where email is the Variable Value for the control storing the email address for a user.
Using Magic Variables in JavaScript
Magic Variables store important data about a Request and are a part of the JSON data model. These variables store information like User name, Process name, and Request ID, etc. All Magic Variables are preceded by an underscore (_
) character in the JSON data model. Use the following syntax to reference a Magic Variable in a Calculated Property:
return this._user.fullname
to reference the user's full name from the in-progress Request. See Magic Variable Descriptions.
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 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.
Edit a Calculated Property for a Screen
Follow these steps to edit a Calculated Property for a Screen:
Edit the settings as necessary and click Save.
Bypass a Calculated Property
Temporary disable a Calculated Property by using the bypass option. Follow these steps to bypass a Calculated Property:
View Logs for a Calculated Property
View developer logs to troubleshoot runtime issues and errors. Follow these steps to view the logs:
When testing a Calculated Property in Screen Preview mode or viewing the Screen in a Case, use the browser function to view the Developer Tools.
Locate any warnings or errors using the name of your Calculated Property in the Developer Tools to verify if it has successfully run.
Delete a Calculated Property
When a Calculated Property is deleted, in-progress Cases using that Calculated Property are not affected. However, the Calculated Property cannot be referenced in new Cases or other Process models afterward.
Deleting a Calculated Property from the Calculated Properties page is irreversible.
Follow these steps to delete a Calculated Property from a Screen:
Last updated