Tracker Relations

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.

IRelations 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).

Watch a video on tracker relations here.

There are two types of relations between tracker items:

• References and
• Associations.

References

References are relations bound to Reference Fields of tracker items (see Creating and Customizing Trackers).

Reference fields are similar to Foreign Keys in Relational Databases, and

• can be required/mandatory
• can refer to multiple items
• can refer to items from multiple target trackers
  • even from trackers in other projects
• 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.

• A Test Case Verifies a Requirement
• The Subject to be approved by an approval Task.

The Cardinality of references can be configured to be

• 0..1
  if the field is not mandatory and only allows a single value
• 1
  if the field is mandatory and only allows a single value
• 0..* or *
  if the field is not mandatory and allows multiple values
• 1..*
  if the field mandatory and allows multiple values
• x..y
  where x and y are the Min(imum) and Max(imum) (number of) values of the reference field.

You can also define Constraints between reference fields (of the same tracker), e.g.

• If field A refers to an item of tracker X
• Then field B must refer to an item of tracker Y
• Where the item in B must refer to the item in A via the reference field C (of tracker Y)

See Dynamic pick-list fields for more information about: Dynamic/Relation based dependencies between reference fields.


The

• Inheritance
• and Reference

relations between trackers can also be visualized as a diagram by clicking on Configuration Diagram on the Trackers page:





In the diagram:

• Trackers are shown as nodes
• Inheritance is shown as blue Generalization arrows from the derived tracker to the template tracker
• References are shown as light blue arrows from the declaring reference field to the target trackers

We can change the visibility of trackers on the left tree by clicking on trackers.

The selected tracker list is saved, so when the configuration diagram is opened again then the last saved selected tracker list is displayed.

References can be used to

• find/filter items referring to/referenced by other items in
  • Tracker Views
  • You must login to see this link. Register now, if you have no user account yet.
• Update Referring Items
• Create new Upstream-Downstream referring items

Depending on the current point of view (Tracker), References can be

• Upstream or
• Downstream .

Upstream References

Upstream references are defined by reference fields in the current tracker.

Downstream References

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.

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 expect the suspection control will be reversed.
• 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.

Reference Tracking

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
• test Test Case has also an assocation 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).

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 Table Views.

Specialized Reference Tracking Views

There are also other specialized Reference Tracking Views. E.g.:

• Release Management with codebeamer
• Traceability Matrix
• Traceability Browser (7.9)

But be warned, that some of these views rely on specific reference fields, e.g.

• Release Management with codebeamer only shows (work) items assigned to a (Target) Release via the reference field with property/attribute name versions.

Associations

Associations are ad-hoc relations (like clamps) between tracker items and

• other CodeBeamer entities like
  • other items
  • or documents,
• even with external web resources.

In contrast to References, Associations have neither a defined

• Value Set,
• Cardinality
• nor Permissions.

Everybody with access to a tracker items can create new item associations (in any item status) via Add Association on the Associations tab.

You can neither enforce that a specific association should exist nor prevent the existence of associations.


The Type of an association gives an indication about the purpose/meaning of this association.

For example: The item

• depends on
• is related to
• is derived from
• violates
• excludes
• invalidates
• is a copy of

the other/target object.

Suspected links

If both associated objects are tracker items, the association can be marked to

• Propagate suspects

which means,

• whenever the associated target item gets modified, the association (owner) will be flagged as Suspected link.

These suspected links are quite dumb, because

• You cannot configure, what are relevant modifications and what can be ignored.
• Simply any change will trigger a Suspect.

Work Item Traceability

From codeBeamer 8.2 on the Work Item page there is a Traceability section instead of the Relations box, see details here: Work Item Traceability