Downstream Reference Functions
 |
When using calculations with a downstream reference function, consider that they may impact the Codebeamer performance and lead to an increased load on the server. This is due to the following reasons:
• A computation always requires a database query.
• The results of the computation are not cached.
• A computation can return an unpredictable number of results, potentially consisting of hundreds of thousands of rows.
PTC recommends that you test the downstream reference formulas in a non-production environment first and use realistic data when executing the load tests.
|
|
Function
|
Signature
|
Meaning
|
Availability
|
|---|---|---|---|
|
downstreamReferences(this)
|
List downstreamReferences(TrackerItemDto upstreamItem)
|
Returns list of downstream referenced items from the specified upstream item with the specified filter criteria. Criteria can be specified fluently by calling additional functions on the lazily built list result:
• List trackerTypes(String... trackerName)—Include only downstream referenced items from the specified tracker types. Default: all tracker types.
• List sharedFieldNames(String... sharedFieldName)—Include only the references that are tagged with any of the specified shared field names (global types). Default: no restriction.
• List trackerIds(Integer.. trackerId)—Include only the downstream referenced items from the specified trackers. Default: all trackers.
|
Codebeamer 22.10-LTS and newer
|
 |
(this) can be omitted from the formula, as downstreamReferences(this) and downstreamReferences yield the same results.
|
|
|
Deleting a Tracker does not trigger any calculated fields.
|
The usage of the downstream reference functions has the following restrictions:
• Downstream and upstream references cannot be mixed in the same formula. The following example shows an invalid mix of downstream and upstream references:
downstreamReferences(subjects[0]).{ref|ref.name}
• The calculation is done only one level down on the reference chain, and nested downstreamReferences function calls are not allowed. The following example shows an invalid nesting of downstreamReferences functions:
sum(downstreamReferences(this).{ref|downstreamReferences(ref).{dsr|dsr.storyPoints}})
When an invalid formula is used, you cannot apply the settings when editing a field and you cannot save the modified tracker configuration.
The downstreamReferences expression can be used together with other filters.
Examples of downstreamReferences Usage
|
Function
|
Meaning
|
|---|---|
|
downstreamReferences(this).trackerTypes("task","user story").{item| item.name}
|
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).sharedFieldNames("shared_field_name1","shared_field_name2").{item | item.name}
|
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).trackerIds(<ID of Tasks tracker>,<ID of Test Cases tracker>).{item | item.name}
|
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>).sharedFieldNames("shared_field_name1").{item | item.name}
|
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).trackerTypes("task","user story").{item | item.fieldId == 17 ? item.name : null}
|
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 source/base item from ID 17. If a reference is through another field, do not list the item
|