Share this page
Value formulas
You can define a business rule that sets a field's value based on the evaluation of a JavaScript formula.
Overview
The JavaScript formula can consist of a single JavaScript expression on a single line. The result of the expression must match the value type of the field that is being set. There is no validation of the type match. The supported functions, methods, and operators are listed in the sections below.
As you type the expression in the formula box, autocomplete suggests the right fields and functions.
Aviator: In the Aviator box, you can describe the calculation in your own words. Aviator will convert your description into a JavaScript formula.
Namespace conventions: Functions are accessed through namespaces such as Math, Date, DateUtils, MathUtils, CollectionUtils, and Context. String and collection operations can be called directly on field values using dot notation.
Comparison and logical operators
The following comparison and logical operators are supported for evaluating conditions.
| Operator | Example | Description |
|---|---|---|
| == | entity.story_points.value == entity.actual_story_points.value | Equality operator. Note: For date fields, use DateUtils.isEqual() instead. |
| != | entity.story_points.value != entity.actual_story_points.value | Inequality operator. Note: For date fields, use DateUtils.isEqual() with negation instead. |
| > | entity.story_points > entity.actual_story_points | Greater than |
| < | entity.story_points < entity.actual_story_points | Less than |
| >= | entity.story_points >= entity.actual_story_points | Greater than or equal to |
| <= | entity.story_points <= entity.actual_story_points | Less than or equal to |
| && | (entity.story_points > entity.actual_story_points) && (entity.bucket_rank < entity.udf) | Logical AND. Returns true only if both conditions are true. |
| || | (entity.story_points > entity.actual_story_points) || (entity.bucket_rank < entity.udf) | Logical OR. Returns true if at least one condition is true. |
| ! | !(entity.story_points > entity.actual_story_points) | Logical NOT. Negates a boolean condition. |
| ? : | (entity.udf > entity.udf.originalValue) ? entity.udf : entity.udf.originalValue | Ternary operator. Returns the first value if the condition is true, the second value if false. |
Math operations
The following math functions and operators are supported for numeric calculations.
| Function or operator | Example | Description |
|---|---|---|
| + | entity.story_points + entity.bucket_rank_udf | Addition |
| - | entity.story_points - entity.actual_story_points | Subtraction |
| * | entity.story_points * entity.bucket_rank_udf | Multiplication |
| / | entity.story_points / entity.bucket_rank_udf | Division |
| % | (entity.story_points % entity.actual_story_points) | Modulo. Returns the integer remainder of dividing the two operands. For example, 12 % 5 returns 2. |
| Math.min(e1, e2, ...) | Math.min(entity.story_points, entity.actual_story_points, entity.udf) | Returns the smallest of the given numeric expressions. |
| Math.max(e1, e2, ...) | Math.max(entity.story_points, entity.actual_story_points, entity.udf) | Returns the largest of the given numeric expressions. |
| Math.abs(expression) | Math.abs(entity.udf) | Returns the absolute (non-negative) value of the expression. |
| Math.round(expression) | Math.round(entity.udf) | Rounds a value to the nearest integer. |
| Math.floor(expression) | Math.floor(entity.story_points / entity.actual_story_points) | Rounds the value down to the nearest integer. |
| Math.ceil(expression) | Math.ceil((entity.score_udf + entity.business_udf) * entity.story_points) | Rounds the value up to the nearest integer. |
| Math.trunc(expression) | Math.trunc((entity.score_udf - entity.business_udf) * entity.story_points) | Returns the integer part of the expression, removing any fractional component. |
| Math.pow(x, y) | Math.pow(2, 3) | Returns x raised to the power of y (x^y). Example: Math.pow(2, 3) returns 8. |
| MathUtils.avg(t1, t2, ...) | MathUtils.avg(entity.story_points, entity.estimated_time, entity.initial_estimation) | Returns the average (mean) value of the provided numeric terms. |
String operations
The following string methods are supported for manipulating and analyzing text values. All string methods are called directly on a string field using dot notation.
| Method | Example | Description |
|---|---|---|
| substring(start, end) | entity.string_udf.substring(3, 8) | Extracts a substring from the start index up to (but not including) the end index. |
| substr(start, length) | entity.string_udf.substr(2, 5) | Extracts a substring starting at the start index for the specified length. |
| toUpperCase() | entity.string_udf.toUpperCase() | Converts all characters in the string to uppercase. |
| toLowerCase() | entity.string_udf.toLowerCase() | Converts all characters in the string to lowercase. |
| trim() | entity.string_udf.trim() | Removes whitespace from both the beginning and end of a string. |
| trimStart() | entity.string_udf.trimStart() | Removes whitespace from only the beginning of a string. |
| trimEnd() | entity.string_udf.trimEnd() | Removes whitespace from only the end of a string. |
| concat(text1, text2, ...) | entity.string_udf.concat(" ", "Nice try") | Joins two or more strings together. |
| includes(substring) | entity.string_udf.includes("search term") | Checks if a string contains a specified substring. Returns true or false. |
| indexOf(substring) | entity.string_udf.indexOf("search term") | Returns the index of the first occurrence of a substring, or -1 if not found. |
| lastIndexOf(substring) | entity.string_udf.lastIndexOf("search term") | Returns the index of the last occurrence of a substring, or -1 if not found. |
Date operations
The following date methods and operators are supported for date/time calculations and comparisons. Date operations use the Date, DateUtils namespaces.
Creating and parsing dates
| Function | Example | Description |
|---|---|---|
| Date.current() | Date.current() | Returns a date object representing the current date and time. |
| Date.now() | Date.now() | Returns the number of milliseconds elapsed since January 1, 1970, UTC (Unix epoch). |
| Date.parse(dateString) | Date.parse('2025-07-13T08:42') | Parses a date string in ISO format (YYYY-mm-ddThh:mm) and returns its timestamp. |
Date formatting and extraction
| Method | Example | Description |
|---|---|---|
| toUTCString() | entity.creation_time.toUTCString() | Converts a date to a string using UTC (Coordinated Universal Time) format. |
| toDateString() | entity.creation_time.toDateString() | Converts a date to a more human-readable string format. |
| toISOString() | entity.creation_time.toISOString() | Converts a date to ISO 8601 format string. |
| getYear() | entity.creation_time.getYear() | Extracts the year from a date (returns year relative to 1900). |
| getMonth() | entity.creation_time.getMonth() | Extracts the month from a date (returns 0 for January through 11 for December). |
| getDate() | entity.creation_time.getDate() | Extracts the day of the month from a date (returns 1-31). |
| getDay() | entity.creation_time.getDay() | Extracts the day of the week from a date (returns 0 for Sunday through 6 for Saturday). |
| getHours() | entity.creation_time.getHours() | Extracts the hour from a date (returns 0-23). |
| getMinutes() | entity.creation_time.getMinutes() | Extracts the minutes from a date (returns 0-59). |
Date comparisons
| Method or operator | Example | Description |
|---|---|---|
| DateUtils.isEqual(date1, date2) | DateUtils.isEqual(entity.done_date, entity.last_modified) | Checks if two date fields have equal values. Returns true or false. Note: Use this instead of == or != for date comparisons. |
| >, <, >=, <= | Date.current() <= DateUtils.addWeeksToDate(entity.creation_time, 2) | Standard comparison operators for date inequality checks. |
Date calculations
| Method | Example | Description |
|---|---|---|
| DateUtils.diffInMinutes(date1, date2) | DateUtils.diffInMinutes(entity.start_date, entity.end_date) | Calculates the difference between two dates in minutes. |
| DateUtils.diffInHours(date1, date2) | DateUtils.diffInHours(entity.start_date, entity.end_date) | Calculates the difference between two dates in hours. |
| DateUtils.diffInDays(date1, date2) | DateUtils.diffInDays(entity.start_date, entity.end_date) | Calculates the difference between two dates in days. |
| DateUtils.diffInWeeks(date1, date2) | DateUtils.diffInWeeks(entity.start_date, entity.end_date) | Calculates the difference between two dates in weeks. |
| DateUtils.diffInMonths(date1, date2) | DateUtils.diffInMonths(entity.start_date, entity.end_date) | Calculates the difference between two dates in months. |
| DateUtils.diffInYears(date1, date2) | DateUtils.diffInYears(entity.start_date, entity.end_date) | Calculates the difference between two dates in years. |
| DateUtils.addSecondsToDate(date, seconds) | DateUtils.addSecondsToDate(entity.creation_time, 55) | Adds a specified number of seconds to a date. |
| DateUtils.addMinutesToDate(date, minutes) | DateUtils.addMinutesToDate(entity.creation_time, 30) | Adds a specified number of minutes to a date. |
| DateUtils.addHoursToDate(date, hours) | DateUtils.addHoursToDate(entity.creation_time, 2) | Adds a specified number of hours to a date. |
| DateUtils.addDaysToDate(date, days) | DateUtils.addDaysToDate(entity.creation_time, 2) | Adds a specified number of days to a date. |
| DateUtils.addWeeksToDate(date, weeks) | DateUtils.addWeeksToDate(entity.creation_time, 2) | Adds a specified number of weeks to a date. |
| DateUtils.addMonthsToDate(date, months) | DateUtils.addMonthsToDate(entity.creation_time, 2) | Adds a specified number of months to a date. |
| DateUtils.addYearsToDate(date, years) | DateUtils.addYearsToDate(entity.creation_time, 2) | Adds a specified number of years to a date. |
| DateUtils.subtractMinutes(date, minutes) | DateUtils.subtractMinutes(entity.last_modified, 55) | Subtracts a specified number of minutes from a date. |
| DateUtils.subtractHours(date, hours) | DateUtils.subtractHours(entity.last_modified, 2) | Subtracts a specified number of hours from a date. |
| DateUtils.subtractDays(date, days) | DateUtils.subtractDays(entity.last_modified, 3) | Subtracts a specified number of days from a date. |
| DateUtils.subtractWeeks(date, weeks) | DateUtils.subtractWeeks(entity.last_modified, 2) | Subtracts a specified number of weeks from a date. |
| DateUtils.subtractMonths(date, months) | DateUtils.subtractMonths(entity.last_modified, 2) | Subtracts a specified number of months from a date. |
| DateUtils.subtractYears(date, years) | DateUtils.subtractYears(entity.last_modified, 1) | Subtracts a specified number of years from a date. |
Collection utilities
The following utility functions work with collections, lists, and multi-valued fields. Collections include multi-select lists, teams, product areas, and similar entities. All collection utilities use the CollectionUtils namespace.
| Function | Example | Description |
|---|---|---|
| CollectionUtils.count(collection) | CollectionUtils.count(entity.product_areas) | Returns the number of items in a collection. |
| CollectionUtils.includes(list, value) | CollectionUtils.includes(entity.product_areas, "Mobile") | Checks whether a specified value is contained within a list. Returns true or false. |
| CollectionUtils.without(collection, value) | CollectionUtils.without(entity.children.points, null) | Returns a new collection excluding the specified value. |
Length property
The length property works for strings and collections.
| Property | Example | Description |
|---|---|---|
| length |
entity.string_udf.length entity.product_areas.length |
Returns the size of a field's value. The meaning depends on the field type:
|
Original value property
The originalValue property allows you to access a field's previous value before the current update.
| Property | Example | Description |
|---|---|---|
| originalValue | (entity.initial_estimate > entity.initial_estimate.originalValue) ? entity.initial_estimate : entity.initial_estimate.originalValue |
Gets the value that was set to the field before the current update. Note: Available only for Integer, String, and Date field types. Use case: Preserve the maximum value during updates. If an update attempts to set a lower value than the current one, ignore the update and retain the higher stored value. |
Current user properties
The following properties provide access to current user information.
You can read the following properties of the currentUser object: email, fullName, id, name, roles
| Property | Example | Description |
|---|---|---|
| Context.currentUser.email | entity.owner == Context.currentUser.email | Returns the email address of the currently logged-in user. |
| Context.currentUser.name | entity.assigned_to == Context.currentUser.name | Returns the username of the currently logged-in user. |
| Context.currentUser.fullName | entity.created_by == Context.currentUser.fullName | Returns the full name of the currently logged-in user. |
| Context.currentUser.id | entity.owner_id == Context.currentUser.id | Returns the unique identifier (ID) of the currently logged-in user. |
| Context.currentUser.roles | CollectionUtils.includes(Context.currentUser.roles.name, "Workspace Admin") ? "Approve Pending requests" : "Submit new request" | Returns a collection of roles assigned to the currently logged-in user. Use with CollectionUtils.includes() to check for specific roles. |
