Calculated Properties

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.

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.

See best practices when using Calculated Properties

View the Calculated Properties for a Screen

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. to view all Calculated Properties configured for this Screen.

   

3. The following information displays about each Calculated Property:

   1. Property name: The Property Name column displays the name of the Calculated Property.

   2. Description: The Description column displays the description of the Calculated Property.

4. Use the move icon to change the order in which Calculated Properties are displayed in this list.

Add a Calculated Property

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

1. View the Calculated Properties for a Screen.

2. Click the +Property button. The Calculated Properties screen displays settings to configure a 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. This is a required setting.

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

5. From the Formula setting, select Formula icon to enter the value, or mathematical calculation that calculates the property. The Formula icon is selected by default.

6. From the Formula setting, click the JavaScript icon to calculate the property using JavaScript. Using this option allows for referencing the values for Screen controls or Magic Variables.

   

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

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.  

   

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

1. View the Calculated Properties for a Screen.

   

2. Click the Bypass icon for the Calculated Property to temporarily disable it.

3. Click the UnBypass icon to enable the Calculated Property.

View Logs for a Calculated Property

View developer logs to troubleshoot runtime issues and errors. Follow these steps to view the logs:

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

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

1. View the Calculated Properties for a Screen.

   

2. Click the Delete icon for the Calculated Property to delete. The Calculated Property is deleted, and the following message displays: Property deleted.