Understanding calculated field formula syntax

Calculated custom field formulas use the ECMAScript language, which is a subset of JavaScript. If you are familiar with JavaScript, you may be able to create calculated custom field formulas, but there are differences between JavaScript and ECMAScript.

  • Browsers are not used in ECMAScript formulas. There are no objects or methods for actions on the Document Object Model (DOM).
  • You cannot display alerts using ECMAScript.
  • All user input for ECMAScript formulas is provided by values in other Helix ALM item fields.
  • Return statements are not used in ECMAScript. The last line of a formula returns the calculation result.

Only administrators familiar with the scripting language should configure complex formulas for calculated fields. Refer to the ECMA-262 Standard Language Specification (www.ecma-international.org/publications/standards/Ecma-262.htm) for information.

You can create new calculated custom fields as drafts to experiment with formulas without affecting existing items. See Creating draft custom fields.

About ECMAScript functions

Each function has its own syntax rules. If you do not follow these rules, errors are generated when you test the formula or save the calculated field.

  • All standard ECMAScript is supported. Only functions should be used to query input data. See Calculated custom field functions.
  • The scripting language is case sensitive.
  • Text strings, including Helix ALM field names, are entered in double quotation marks. For example, "TextString".
  • Numeric values and variables do not use quotation marks.
  • Each line of code should end with a semicolon (;).
  • You can use two single forward slashes (//) before a line of code to comment it so it does not run as part of the formula. You may want to use comments to help determine lines of code that are not running correctly.
  • The last line of a formula should return a value of the corresponding output type. If you are using a formula in a list item field, the formula must return a numeric value that can be mapped to a list item value to generate as the output.

About code completion

If you manually enter formulas, code completion displays the available functions or properties as you type. Enter a period (.) after an object to display a list of supported functions and properties.

The items in this list change based on the selected object. Scroll through the list to select the functions or property to use. Double-click the function or property or press Enter to add it to the formula.