CodeBeamer organizes tracker items by placing each item in exactly one tracker, which then acts as the container of that items.
But items don't need to exist in complete isolation though, they can have relations to other items in other trackers, even other projects.
Relations are critical for managing, auditing and tracing back changes.
For example, you can trace back which tasks were triggered by which requirements. Then when you also associate your code changes with these tasks, you can take traceability to the next level: you will be able to easily tell which requirements resulted in which source code changes! (see Tracing Source Code Changes to Requirements, Task and Bugs).
can refer to a specific subset of target tracker items (via a filter or view)
The Name of a reference field is synonym for the relation between referring item and reference field values, or in other words, the function or role, that the referring item plays for the reference field values (or vice versa). E.g.
Depending on the current point of view (Tracker), References can be
Upstream references are defined by reference fields in the current tracker.
Downstream references are defined by reference fields of other trackers referring to the current tracker.
Tracker Item Reference Settings
From 8.0.0 you are able to add the following setting to each Tracker Item references:
Baseline or Version: you can select to which Baseline or Version should the reference refer
Propagate suspects: a reference can be propagate suspection (just like an association), and if the referred item changes the reference became suspected.
Reverse suspect: it means that the suspection control is reversed, so if the original item changes (which has the reference) the reference became suspected.
From 9.3.0 some new settings are available:
Bi-directional: this option belongs to the Propagate suspects feature and it means that changes made to the original or to the referred item turn the reference suspected.
Propagate Unresolved Item Dependencies: a reference can propagate unresolved item dependencies, and if an item has unresolved (not resolved or closed) downstream references which are configured to use this setting then the item's UID (unresolved item dependencies) badge become active. This can be configured for associations too.
You can control this settings after adding a reference to a field, by clicking the small arrow within the reference box. An overlay appears where you can select the Baseline or Version and the suspection controls. Please note that if you select a Baseline, the reference will point to the version of the selected Baseline and the version number will appear within the reference box as a badge. Propagate suspect (and reverse) also appears within the box as badges. You will see these badges also in Tracker Item details page.
Setting Default Reference Settings per Field
You are able to set default Reference Setting for a Tracker field. Open the Tracker customization page Fields tab, and click on a reference field (e.g. Subject, Release, etc.). From 8.0.0 you will see the three new settings below the Datasource row:
Propagate suspects: if you check this option, all of the newly added reference item for this field will propagate suspects (the badge will automatically appear after adding the reference).
Reverse suspect: the same as Propagate suspect except the suspection control will be reversed.
Bi-directional: when used then the suspection control is done in both directions for Propagate suspects.
Default version: you have two options here
None (--): it means that the reference will always point to the latest version (so, there is no referring to a Baseline or Version). This is the same behaviour as previously within the codeBeamer. The creation time of the reference does not matter in this case.
Current HEAD: it means that the reference will point always to the current HEAD version (the latest) in time of the creation of the reference. For example: if you set a reference which have the Version 3 in time of the creation of reference, and you change the reference item (ithe current HEAD changes to Version 4), the reference will no more point to the latest version of the item.
Each tracker item, being referenced via a reference field, acts as a (progress) tracker/monitor for the referencing tracker items.
All other items referring to a specific item are listed under the References tab on the item's details page.
For example: Sample Requirement
We can see under Downstream References:
that there is a Test Case reference
it i assigned to bond
it is in Accepted status
the Test Case has also an association and a reference, which has the Suspected flag.
You can filter the Downstream References by type
or by status:
You can also Customize the Downstream References table view (columns) and sorting (per view).
These type of views are no longer supported in codeBeamer version 9.0 and above.
Table Views also support Reference tracking via special Reference Statistics columns:
For each downstream reference to the current tracker, you can show a Reference Statistics column, where Reference is the name of the reference field.
If multiple trackers refer to items of the current tracker via reference fields having the same name, then all these references are summarized in one Statistics column under the common relation name, but
The column will show separate statistics per type of referring item
Plus an extra summary column, if there is more than one referring item type
If there are multiple Reference Statistics columns, you can also show an overall/summary References Statistics column.
Basically, a Reference Statistics column shows
The number of items referring to the current item via a reference field with that name (per item type) versus the number of these items, that are already resolved or closed.
If any of the referring items have Planned or Spent effort:
Plus the overall item progress as total Spent effort versus total Planned effort.
If any of the referring items have Story Points:
Plus the overall item progress as total Story Points of resolved/closed referring items versus total Story Points of all referring items.
For example: Create a new reference tracking view for Processes from the Approval Process example scenario:
Because in the Approval Process example scenario, there is only one other tracker (Approvals) referring to items in the Processes tracker (via the reference field Subject), there is also only one reference statistics column: Subject Statistics.
Adding this column will produce the following result:
Only the number of approval tasks is shown, because we did not configure Planned/Spent effort or Story Points for the approval tasks.
Reference tracking works with any reference field between any type of tracker items and with all Detail and TableViews.
Specialized Reference Tracking Views
There are also other specialized Reference Tracking Views. E.g.: