Computed Fields

This page introduces the concept of computed fields, and gives an in-depth explanation of how such fields can be used and what functions are available in codebeamer.

Tracker fields can be defined as read-only computed fields, where the content is calculated from other tracker item fields. Computed fields can be created by specifying an expression or formula in unified expression language. For more information on the language expressions, see the Syntax section.

Use Cases

Use Case 1: Past Deadline Test (for Issue Resolution)

In this use case, de goal is to display whether the item has already passed the scheduled end date. Click Add custom field at the bottom of the Tracker ► Customize ► Fields tab.

The new custom field is called Past Deadline, and it must be set up as type boolean. The field returns true if the issue is very late. Under the Layout and Content column of the Fields, for the new custom field, the = field is defined as:

not(endDate >= fn:Date("today"))

By checking the box in the List column on the Fields tab, it is possible to have the custom field displayed on the item list or details page. Permissions must be set up under the Permissions tab. A computed field is always read only, write permission is only possible when the field definition is deleted and the field becomes non-computed. For more information about functions available for the computed tracker fields, see the Functions section.

Use Case 2: Weight = Priority * Severity

The goal is to combine issue priority and severity into a new Weight field with the following expression:

Weight = Priority * Severity

Priority is a single choice field with the following choice values:

Severity is a multiple choice field with these defined values:

The highest priority and the highest severity (Blocker) selections both have the lowest ID, so in order to compute a Weight proportional to the logical order of Priority and Severity, such operands must be used that are inversely proportional to the choice value ids.

Example:

integer Weight = (5 - Priority.id) * (6 - Severity[0].id)

An empty Priority or Severity would yield an id of null, so the above formula would return the highest possible weight (= 30) for issues with empty Priority and Severity. To avoid this incorrect result, empty values must be handled appropriately.

Example:

integer Weight = (empty Priority ? 0 : 5 - Priority.id) * (empty Severity ? 0 : 6 - Severity[0].id)

Use Case 3: Compute columns in an embedded table from the values of other columns

From codebeamer 7.3, a tracker (item) can have tables. A table consists of one or more columns:

The first two columns A and B contain numeric operands and the other two columns should contain the product and sum or total of the operands per row.

When addressing a table column, for example by its attribute or property name tableColumn[0,1], then the whole column is addressed always (an array or vector of column values, indexed by row).

Example for the Matrix table:

The expression A or tableColumn[0,0] would yield [1, 2, 3] and B or tableColumn[0,1] would be [5, 6, 7].

To address the whole table, use the name or attribute of the table, for example, Matrix or table[0], which would yield an array of table rows, where each row is an array of table column values (in the order of the columns).

[
  [1, 5],
  [2, 6],
  [3, 7]
]

The index of the first row is 0 and the first table row can be accessed via one of the following ways:

• table[0][0]
• Matrix[0]

This would yield [1, 5].

To address the value of Column A (tableColumn[0,0]) in the second row of the Matrix, write:

• table[0][1][0]
• Matrix[1][0]
• tableColumn[0,0][1]
• A[1]

So how can we define a third column Product, whose value is the product of A multiplied by B (for each row)?

If the Product is defined to be computed as

• tableColumn[0,0] * tableColumn[0,1]
• or simply A * B,

Then this would mean a multiplication of two vectors, for example, [1, 2, 3] * [5, 6, 7], an operation not supported by the expression language.

Also the result would be a two dimensional array, and not a one-dimensional column value vector.

The solution is to to use a projection: table.{ row | expression } that iterates over each row in the table and produces an array of values, one value per row according to expression.

The projection or expression is the following:

table[0].{row | row[0] * row[1] }

It reads as follows:

• Iterate over table[0]
  • for each row(an array of column values)
    • evaluate the expression row[0] * row[1]
• return an array of the expression values per row

For the example table, the result is the array or vector: [5, 12, 21]

Changes from codebeamer 20.11

Before codebeamer 20.11, a column index was interpreted as the ordinal index of the column in the table columns list. Adding, removing or re-ordering columns could therefore change the ordinal index of a column.

The ordinal index of Product, that was 2, is now 3, which leads to an inconsistency in table cell access via table column index: table[0][row][3] != tableColumn[0,2][row]

From codebeamer 20.11, a column index is always interpreted as the immutable and unique column id, which is the second index in the immutable and unique column property name.

For example the column id or index of Product (tableColumn[0,2]) is 2, independent of its position. Adding, removing or re-ordering columns will not change the column id or index of existing columns and column access stays consistent: table[0][row][2]==tableColumn[0,2][row]

Using Computed Fields

Syntax

Unified expression language syntax is used for the formulae of field values. The expression language defines the following literals:

• Boolean: true and false
• Integer: as in Java
• Floating point: as in Java
• String: with single and double quotes; " is escaped as \", ' is escaped as \', and \ is escaped as \\ .
• Null: null

In addition to the . and [] operators, the expression language provides the following operators:

• Arithmetic: +, - (binary), *, / and div, % and mod, - (unary)
• Logical: and, &&, or,||, not, !
• Relational: ==, eq, !=, ne, <, lt, >, gt, <=, ge, >=, le. Comparisons can be made against other values, or against boolean, string, integer, or floating point literals.
• Empty: the empty operator is a prefix operation that can be used to determine whether a value is null or empty.
• Conditional: A ? B : C. Evaluate B or C, depending on the result of the evaluation of A.
• Projection: .{alias|expression} is a special operator on collections that iterates over the collection and creates a new collection by evaluating the specified expression or subexpression for each element alias of the original collection.

The precedence of operators in descending order and from left to right is the following:

• [] .
• () - Used to change the precedence of operators.
• - (unary) not ! empty
• * / div % mod
• + - (binary)
• < > <= >= lt gt le ge
• == != eq ne
• && and
• || or
• ? :

The following words are reserved for the JavaServer Page expression language and should not be used as identifiers.

• and
• div
• empty
• eq
• false
• ge
• gt
• instanceof
• le
• lt
• mod
• ne
• not
• null
• or
• true

For more information on the Unified Expression Language, see the Java EE 5 Tutorial.

Context Variables

The execution or evaluation context of a unified expression contains the following objects:

It is possible use the dot (.) operator to access attributes of context objects, for example, user.realName or project.name.

To access attributes (fields) of the current tracker item (this), users can ommit this. in front of the attribute or field identifier. For example, submitter is equivalent to this.submitter.

To refer to the value of tracker item fields, the following field identifiers are allowed:

• The field property or attribute name, such as id, name, description, submitter, submittedAt, namedPriority, status, assignedTo, subjects, categories, versions, customField[0], choiceList[2], etc.
• Field label, but only in the following cases:
  • If the label only consists of alphanumeric characters ([A-Z],[a-z],[0-9]), ‘$‘(dollar sign) and ‘_‘ (underscore).
  • The label does not start with digits ([0-9]).
  • The label does not contain HTML markup.
  • For example, Color is allowed, but Background color, Best.-Nr., Estimated<br/>Effort or <b>v</b>_max (v_max) are not allowed
• The RESTful field name (lower camel case of field label, with all HMTL markup and not allowed characters removed), for example, color, backgroundColor, bestNr, estimatedEffort and vmax.

The property and label of the field is displayed in their respective columns in the Tracker ► Customize ► Field Properties area.

For static choice fields in codebeamer 9.3 and newer, users can also refer to the following options:

• The list of defined choice field options: choiceField_$options. For example, status_$options or choiceList[1]_$options
• A specific choice field option, per option id or lowercase option name: choiceField_$option[idOrName]. For example, status_$option["new"], namedPriority_$option["high"] or choiceList[1]_$option[2]. Instead of choice option names, option ids can be used. Option ids are safer but using option names can be more convenient or easier to understand.

To access individual values of multi-value choice fields, use the [] operator, for example, categories[0], choiceList[2][0].

To access attributes of complex field values, such as choice values, use the . operator followed by the attribute. For example, Priority.id, Status.name, Resolution[0].name.

All references, choice and members field values have at least the following attributes:

• id Integer
• name Text

To extract attributes from a multi-value field, use a projection. For example, to create a list of the names of all users or roles assigned to the item, users can use the following syntax:

assignedTo.{member|member.name} 

Users can use such a projection in combination with the function valuesInList to check if the item is assigned to some particular users.

Example:

fn:valuesInList(assignedTo.{member|member.name}, “bond”, “Project Admin”) ?

Functions

String-Related Functions

Function	Signature	Meaning	Availability
concat	String concat(Object...)	Converts all parameters to strings and concatenates them to a single result string.	codebeamer 5.4 and newer
contains	boolean contains(String text, String part)	Tests, if the specified text contains the specified part.	codebeamer 5.4 and newer
containsIgnoreCase	boolean containsIgnoreCase(String text, String part)	Tests, if the specified text contains the specified part, irrespective of case.	codebeamer 5.4 and newer
endsWith	boolean endsWith(String text, String suffix)	Tests if the specified text ends with the specified suffix.	codebeamer 5.4 and newer
escapeXml	String escapeXml(String text)	Escapes characters with a special meaning in XML with appropriate escape sequences.	codebeamer 5.4 and newer
format	String format(String pattern, Object... args)	Create a string representation of the specified arguments using a MessageFormat pattern.	codebeamer 5.4 and newer
indexOf	int indexOf(String text, String part)	Finds the first index of the specified part within text, or -1 if not found.	codebeamer 5.4 and newer
join	String join(String[] array, String separator)	Joins the elements of the provided array into a single String, separated by the separator.	codebeamer 5.4 and newer
length	int length(Object)	Returns the length of the passed string, or the number of elements of the passed array or collection.	codebeamer 5.4 and newer
printf	String printf(String format, Object... args)	Create a string representation of the specified arguments using a printf like format.	codebeamer 5.4 and newer
replace	String replace(String text, String replace, String replacement)	Replaces a String with another String inside a larger String.	codebeamer 5.4 and newer
split	String[] split(String text, String separator)	Splits the provided text into an array (at each occurence of the separator).	codebeamer 5.4 and newer
startsWith	boolean startsWith(String text, String prefix)	Tests if the specified text starts with the specified prefix.	codebeamer 5.4 and newer
substring	String substring(String text, int start, int end)	Gets a substring from the specified String, from the start position (inclusive) to the end position (exlusive).	codebeamer 5.4 and newer
substringAfter	String substringAfter(String text, String separator)	Gets the substring after the first occurrence of the separator.	codebeamer 5.4 and newer
substringBefore	String substringBefore(String text, String separator)	Gets the substring before the first occurrence of the separator.	codebeamer 5.4 and newer
substringBetween	String substringBetween(String text, String open, String close)	Gets the substring after the first occurrence of the open string and before the occurance of the close string.	codebeamer 5.4 and newer
toLowerCase	String toLowerCase(String text)	Converts a String to lower case.	codebeamer 5.4 and newer
toUpperCase	String toUpperCase(String text)	Converts a String to upper case.	codebeamer 5.4 and newer
trim	String trim(String text)	Removes leading and trailing whitespace.	codebeamer 5.4 and newer

Functions for Random String Generation

The case of function names is significant. Using the fn: prefix is optional when referring to functions.

Examples:

concat(customField[3], " ", customField[4], " has downloaded and installed codeBeamer.")

fn:format("{0,date,yyyy-MM-dd HH:mm}", submittedAt)

List-Related Functions

For single value attributes, such as status, priority or submitter, users can use valueInList().

Example: check if the name of the user that has submitted the item is “bond” or “klaus”:

valueInList(submitter.name, "bond", "klaus")

For attributes with multiple values (for example, assignedTo, supervisors, subjects, versions, and all custom choice lists), checking for constant values requires valuesInList() in combination with a projection.
For example, to check if the issue owner or supervisors list contains any of the specified users by name:

valuesInList(supervisors.{principal|principal.name}, "bond", "klaus")

The function objectIdsInList() is functionally equivalent to:

valuesInList(objects.{object|object.id}, ids)

Example: check if the Resolution field contains a value with ID 2 or 4:

objectIdsInList(resolutions, 2, 4)

or

valuesInList(resolutions.{resolution|resolution.id}, 2, 4)

Mathematical Functions

Function	Signature	Meaning	Availability
Integer	Integer Integer(Object value)	Returns an Integer, if the specified value is a numeric value, e.g. a Number or a numeric string, otherwise null.	codebeamer 9.3.0 and newer
Number	Number Number(Object value)	Returns a Number, if the specified value is a numeric value, e.g. a Number or a numeric string, otherwise null.	codebeamer 9.3.0 and newer
random	Double random()	Generates a pseudo random number in the range [0 .. 1).	codebeamer 9.3.0 and newer
sin	Double sin(Number angle)	Returns the trigonometric sine of an angle (in radians).	codebeamer 9.3.0 and newer
cos	Double cos(Number angle)	Returns the trigonometric cosine of an angle (in radians).	codebeamer 9.3.0 and newer
tan	Double tan(Number angle)	Returns the trigonometric tangent of an angle (in radians).	codebeamer 9.3.0 and newer
asin	Double asin(Number value)	Returns the arc sine of a value; the returned angle is in the range [-π/2 .. π/2].	codebeamer 9.3.0 and newer
acos	Double acos(Number value)	Returns the arc cosine of a value; the returned angle is in the range [0 .. π].	codebeamer 9.3.0 and newer
atan	Double atan(Number value)	Returns the arc tangent of a value; the returned angle is in the range [-π/2 .. π/2].	codebeamer 9.3.0 and newer
toRadians	Double toRadians(Number angle)	Converts an angle measured in degrees to an approximately equivalent angle measured in radians.	codebeamer 9.3.0 and newer
toDegrees	Double toDegrees(Number radians)	Converts an angle measured in radians to an approximately equivalent angle measured in degrees.	codebeamer 9.3.0 and newer
exp	Double exp(Number x)	Returns ex, where e is Euler's number.	codebeamer 9.3.0 and newer
sinh	Double sinh(Number x)	Returns the hyperbolic sine of a value, that is defined to be: (ex - e-x) / 2	codebeamer 9.3.0 and newer
cosh	Double cosh(Number x)	Returns the hyperbolic cosine of a value, that is defined to be: (ex + e-x) / 2	codebeamer 9.3.0 and newer
tanh	Double tanh(Number x)	Returns the hyperbolic tangent of a value, that is defined to be: (ex - e-x) / (ex + e-x), in other words: sinh(x) / cosh(x).	codebeamer 9.3.0 and newer
log	Double log(Number x)	Returns the natural logarithm (base e) of a value: ln(x) or loge(x)	codebeamer 9.3.0 and newer
log10	Double log10(Number x)	Returns the base 10 logarithm of a value: log10(x)	codebeamer 9.3.0 and newer
sqrt	Double sqrt(Number x)	Returns the (positive) square root of a value: √x	codebeamer 9.3.0 and newer
cbrt	Double cbrt(Number x)	Returns the cube root of the value: ∛x	codebeamer 9.3.0 and newer
pow	Number pow(Number x, Number y)	Returns the value of x raised to the power of y: xy	codebeamer 9.3.0 and newer
abs	Number abs(Number x)	Returns the absolute value: |x|	codebeamer 9.3.0 and newer
floor	Long floor(Number x)	Returns the largest integer value ≤ x.	codebeamer 9.3.0 and newer
ceil	Long ceil(Number x)	Returns the smallest integer value ≥ x.	codebeamer 9.3.0 and newer
round	Long round(Number x)	Returns the integer value, that is closest to x.	codebeamer 9.3.0 and newer
signum	Integer signum(Number x)	Returns -1, 0 or 1, depending on whether the number is less, equal or greater than 0.	codebeamer 9.3.0 and newer

Net Working Time Functions

The functions for net working time are based on the System default and Project specific working time settings.

Date-Related Functions

The date parameter for the Date function can be either an absolute date or string constants. The absolute date can be specified as "yyyy-MM-dd[ HH:mm[:ss]]". Optionally, the times zone can be specified the following way:

• "UTC" if the literal represents coordinated universal time.
• "default", "system", or "local" if the literal represents default, system, or local time of the codeBeamer installation/server.
• As time zone offset from GMT as "GMT[±][hh[:mm]]".
• As a time zone abbreviation.
• If no timezone for the date is specified, the default is the time zone of the current user. If there is no current user or the user does not have a special time zone setting, the default time zone of the codebeamer system.

The date parameter can be also specified with one of the following string constants:

• "Now"
• "Today"
• "Tomorrow"
• "Yesterday"
• "Start of this week"
• "End of this week"
• "Start of next week"
• "End of next week"
• "Start of last week"
• "End of last week"
• "Start of this month"
• "End of this month"
• "Start of next month"
• "End of next month"
• "Start of last month"
• "End of last month"
• "Start of this year"
• "End of this year"
• "Start of next year"
• "End of next year"
• "Start of last year"
• "End of last year"

Example:

endDate >= Date("today")

The precision for roundDate and truncateDate and the unit of shiftDate and timeBetween must be an abbreviation of:

• "Year"
• "Month"
• "Week"
• "day"
• "hour"
• "minute"
• "second"

Example:

roundDate(endDate, "h")
shiftDate(startDate, 30, "min")

User-Related and Group-Related Functions

User Permission Functions

The groups parameters for the function userInGroup, are the names of user groups:

There can be any number of additional user groups.

In most cases, it is more appropriate to check if a user has a specific system permissions (that can be granted via different user groups). For example instead of

userInGroup(user, "sysadmin")

use

userHasPermission(user, "system_admin")

The roles parameter for the userInRole function are the names of project roles.

There can be any number of additional project roles.

Example: check if the current user has the role Developer or Tester in the current project:

userInRole(user, project, "Developer", "Tester")

In most cases, it is more appropriate to check if a user has a specific project permission (that can be granted via different project roles). For example, instead of

userInRole(user, project, "Project Admin")

use

userHasProjectPermission(user, project, "project_admin")

The permissions parameters for the userHasPermission function are the names of system permissions:

System permissions are granted to user groups and indirectly to all users in that groups.

The permissions parameters for the userHasProjectPermission function are the names of project permissions:

Project permissions are granted to project roles and indirectly to all project members with that roles.

The permissions parameters for the userHasTrackerPermission function are the names of tracker permissions:

Tracker permissions are granted to project roles via Tracker ► Customize ► Permissions, and so indirectly to all project members in that roles.

Suspected Reference Functions

Example: check if the tracker item does not have suspected links:

!hasSuspectedLink(this)

Example: check if the tracker item has upstream suspected links and does not have downstream suspected links:

hasUpstreamSuspectedLink(this) and !hasDownstreamSuspectedLink(this)

Downstream Reference Functions

Using downstream reference functions has the following restrictions:

• Downstream and upstream references cannot be mixed in the same formula. Example of a restricted formula:
  

  downstreamReferences(subjects[0]).{ref|ref.name}
  

• The calculation is done only one level down on the reference chain (nested downstreamReferences function calls are not allowed). Example of a restricted formula:
  

  sum(downstreamReferences(this).{ref|downstreamReferences(ref).{dsr|dsr.storyPoints}})

When a restricted formula is used, it is not possible to apply the settings at editing or to save the modified tracker configuration.

The downstreamReferences expression can be used together with other filters.

Example: list those items by item name to which this tracker item has downstream reference, and the tracker type is task or user story.

downstreamReferences(this).trackerTypes("task","user story").{item| item.name}

Example: list those items by item name to which this tracker item has downstream reference, and the name of the shared field is "shared_field_name1" or "shared_field_name2".

downstreamReferences(this).sharedFieldNames("shared_field_name1","shared_field_name2").{item | item.name}

Example: list those items by item name to which this tracker item has downstream reference, and the tracker id is <ID of Tasks tracker> or the test case tracker id is <ID of Test Cases tracker>.

downstreamReferences(this).trackerIds(<ID of Tasks tracker>,<ID of Test Cases tracker>).{item | item.name}

Example: list those items by item name to which this tracker item has downstream reference, and the tracker id is <ID of Tasks tracker> or the test case tracker id is <ID of Test Cases tracker> and the name of the shared field is "shared_field_name1".

downstreamReferences(this).trackerIds(<ID of Tasks tracker>,<ID of Test Cases tracker>).sharedFieldNames("shared_field_name1").{item | item.name}

Example: list those items by item name to which this tracker item has downstream reference, and the tracker type is task or user story. List only those items by item name that are referencing the field with the field id "17", if a reference is through another field, do not list the item.

downstreamReferences(this).trackerTypes("task","user story").{item | item.fieldId == 17 ? item.name : null}

Special Functions

Function Examples

The priority of the task should reflect the highest priority of all subjects:

max(subjects.{subject|subject.priority})

Example:
A bug refers to one or more builds, that are affected by this bug (via a custom reference field, for example, choiceList[1]).
Each build is a configuration item, that itself refers to a release (via the Versions field). Different builds can belong to the same release.
The field Detected in (Release) of the bug should now be automatically computed to reflect the releases of all builds affected by this bug:

distinct(choiceList[1].{build|build.versions.{version|version}})

Example of a nested projection execution:

List result;
for (Object build in choiceList[1]) {
  for (Object version in build.versions) {
     result.add(version);
  }
}
return distinct(result);

Example: the severity of an item should be the highest severity of all subjects:

List(min(subjects.{subject|subject.severities.{severity|severity}}))

or

first(1, ascending(subjects.{subject|subject.severities.{severity|severity}}))

Note that Severity is a choice list/field, so the field value is a list of choice options. By default, only one list element is allowed. Severity choice options are ordered descending from highest to lowest, so users must use min or first in order to get the highest severity.

Example: Show the last two comments on the tracker item:

join(first(2, reverse(distinct(attachments.{attachment|attachment.description}))).toArray(), "\\\\")

That reads as:

• Collect the comments of all attachments:

  attachments.{attachment|attachment.description} 

• Remove all duplicates and empty comments:

  distinct(...)

• Reverse the order of comments (last comment first):

  reverse(...)

• Extract the first 2 comments (due to reverse order, these are the last/newest 2 comments in descending order):

  first(2, ...)

• Concatenate the comments into a single string, separated by a Wiki line break:

  join(... .toArray(), "\\\\")

Computed Field Dependencies

A computed field can use reference fields in its formula. Before codebeamer 9.5, these computed field values were recalculated when the item was updated. Starting from codebeamer 9.5, the field value can be recalculated whenever an item the formula depends on is updated. For this to work efficiently, codebeamer must store the dependencies of the custom fields. It is possible to check these dependencies by clicking on the Compute Dependencies link under the computed field formula text area. This parses the formula and show the dependencies if the custom field has any. The list consists of the the trackers and fields on which the formula depends. The Fields checked during update section shows every field per tracker on which the computed field depends. When these fields change, the computed field is updated.

The dependency list cannot be computed automatically in the following cases:

• When the formula is very complex.
• When the fields used in the formula refers a tracker type not a tracker explicitly.

In these cases, users can add a dependency manually using the select lists under the text area.

• Project and Tracker: the tracker of the referring field on which the formula depends.
• Field: the field on which the formula depends.
• Referred Tracker: a tracker referred by the field. If an item from this tracker referenced through the field is updated then the formula is recalculated.