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.

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

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 codeBeamer, 8.0.0, you are able to specify the following settings for each tracker item reference:

• Baselines or Versions: the baseline(s) or version(s) to which the reference refers. Note: you can only specify a value (or values) for one of these two options. If you select a value for one of these options, the other option will be made inactive.
• Propagate suspects: specifies whether the reference propagates suspicion. If this option is selected, the reference is marked as "Suspected" in case the referred item is modified. You can then decide whether the change in the referred item applies to your work item, and you can easily apply the changes in the referred item to the work item if necessary.
• Reverse direction: specifies that the control of suspicion is reversed. If this option is selected, the reference is marked as "Suspected" in case the original work item (which contains the reference) is modified. Note: this option belongs to the "Propagate suspects" feature, and you can only select this option if the "Propagate suspects" checkbox is checked.

From codeBeamer 9.3.0, the following settings are also available:

• Bi-directional: specifies that the control of suspicion is bi-directional. If this option is selected, the reference is marked as "Suspected" in case either the original work item or the referred item is modified. Note: this option belongs to the "Propagate suspects" feature, and you can only select this option if the "Propagate suspects" checkbox is checked. Also, you cannot select both "Reverse direction" and "Bi-directional" at the same time. If the checkbox for one of these options is checked, the other option is automatically deselected.
• Propagate Unresolved Item Dependencies: specifies whether the reference propagates unresolved item dependencies. If this option is selected, the item's UID (Unresolved Item Dependencies) badge becomes active in case the item has unresolved (not resolved or closed) downstream references which are configured to use this setting. Note: this option cannot be used together with the "Reverse direction" option. If this option is selected, the "Reverse direction" option is made inactive. Also, if the "Propagate Unresolved Item Dependencies" option is selected, it is not possible to specify a baseline or version for the reference.

To specify these settings for a reference, click the Reference Settings arrow in the reference field:

When you have specified all the settings as applicable, click OK. All the selected options will now be displayed in the reference field as badges. For example:

Note: If you select a baseline for the reference, the reference will point to the current version of the selected baseline, and the version number will appear within the reference box as a badge:

The badges for the selected options will also be displayed on the Details panel of the item in the Document view of the tracker.

Propagate Suspects - Checking and Applying Changes and Clearing Suspicion

In case the "Propagate Suspects" option (with or without any of its sub-options) is specified for a reference, changes in the reference (and/or in the original work item) will be displayed when you open the item:

The direction of the arrow displayed together with the "Suspected" badge can be the following:

• Upward arrow: indicates that an upstream reference has been modified.
• Downward arrow: indicates that a downstream reference has been modified.

Changes in a reference will also be displayed on the items's Details panel in the Document view of the tracker which the item belongs to:

To check the changes made in a reference or to apply the changes to the work item (or the other way round), follow the steps below:

1. Click the badge in the reference field:

The following window opens with a list of all fields where the values are different in the two items:

Note: This tab displays all differences between the two items not only the fields which have been modified now and which triggered the "Suspected" badge.

If the Show different fields only option is selected (top right-hand corner), the system only displays the fields where the values are different in the two items. If this option is not selected, all the fields of the items are displayed (including empty fields).

2. To check the changes in the referred item which triggered the "Suspected" badge, click the Changes tab. To check the changes made in the original work item, go to the Derived Item Changes tab:

3. To merge recent changes or any other differences between the two work items, use the Apply buttons on the Merge tab:

You can decide which way you want to merge changes: from the referred item to the work item or the other way round. Use the leftward and rightward arrows in the Apply fields to merge changes as applicable.

You can easily apply all changes from one item to the other at the same time by using one of the Apply arrow buttons in the top row:

Note: It is only possible to merge differences and changes between work items of the same type, for example, Requirements or User Stories. In case the original work item and the referred item are of different types (for example, a Software Task has an upstream reference which is a Requirement or a User Story), the Merge tab will not be available when you click the "Suspected" badge.

4. To clear the suspicions without merging any changes, click the Clear Suspected checkbox in the top left-hand corner:

In case the Omit Merge option is set for any field in the tracker (see section "Setting Default Reference Settings per Field"), changes made in that field will be listed under "Fields not merged automatically" on the Merge tab:

5. When you are finished merging changes, click Save to apply the changes.

To close the Merge window without merging any changes, click Cancel, or click the icon in the top right-hand corner of the window.

Note: You can also clear a suspicion by clicking the icon next to the "Suspected" badge in the reference field (without opening the Merge tab):

The system will ask for a confirmation:

Click Yes.

Propagate Unresolved Item Dependencies

If the "Propagate Unresolved Item Dependencies" option is selected for a downstream reference in a work item, the UID badge will be displayed next to the item in the tracker's Table view and on the Details page of the item in the tracker's Document view. For example:

If you click the UID badge next to a work item, the system will display a list of all unresolved items that the work item is dependent on:

The UID badge is also displayed in the breadcrumb navigation bar of the work item, as well as in the Traceability field and on the Associations tab next to the item that the original work item is dependent on. For example:

Note: the "Propagate Unresolved Item Dependencies" option can only be applied between work items, except for test runs, reviews, and SCM related items. In case you are trying to add a reference to a work item, and the referred item is a test run, the "Propagate Unresolved Item Dependencies" option will not be available.

Note: if the "Propagate Unresolved Item Dependencies" option is selected for a reference in a work item, codeBeamer will apply this setting in a bidirectional way. That is, the UID badge will also be displayed next to the original work item in the Traceability field and on the Associations tab of the referred item.

Setting Default Reference Settings per Field

CodeBeamer allows you to set default reference settings for a tracker field. To set default reference settings for a reference field, open the tracker configuration page and select the Fields tab. Click on a reference field (for example, Subject or Release). From codeBeamer 8.0.0 and 9.3.0 (see section Tracker Item Reference Settings), the following options are also available in the Edit:<reference_field>window:

• Propagate suspects: if this option is selected, all reference items added to this field will propagate suspects in cases when the referred item is modified (the "Suspected" badge will automatically appear after adding the reference).
• Reverse direction: if this option is selected, all reference items added to this field will propagate suspects in cases when the original work item is modified.
• Bi-directional: if this option is selected, all reference items added to this field will propagate suspects in cases when the referred item or the original work item is modified.
• Default version: the following values are available in this field:
  • None (--): it means that the reference will always point to the latest version available (that is, there is no reference to a baseline or version), irrespective of the time of creation of the reference.
  • Current HEAD: it means that the reference will always point to the current HEAD version, that is, the latest version at the time of creation of the reference. For example, if you create a reference when the current HEAD version is version 3, and then a new baseline version is created (that is, the current HEAD version changes to version 4), the reference will still point to version 3 of the baseline.

The following two fields have been added to all tracker fields:

• Omit Suspected when changing: if this option is selected for any field in a tracker, modifications in that field will not activate the "Suspected" badge for references. That is, even if the "Propagate Suspects" feature is activated for a reference, and modifications are made in this specific field in the referred item (or in the original work item), the "Suspected" badge will not be activated for the reference.
• Omit Merge: if this option is selected for any field in a tracker, modifications in that field will not activate the "Merge" function for references. That is, even if the "Propagate Suspects" feature is activated for a reference, and modifications are made in this specific field in the referred item (or in the original work item), the "Merge" function will not be activated for this modification. The modification will still be listed on the Merge tab under "Fields not merged automatically", but it will not be possible to merge this change from one item to the other.

Reference History For Fields

Application stores the most recently added values for each tracker field. This list is specific to each user and tracker field combination. Field editor shows these stored values as suggestions, when the user clicks on it.

Users can configure this feature on Preferences dialog. See User Preferences wiki page for more information about the related setting.

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 Task

We can see under Downstream References:

• that there is a Test Case reference
• it is submitted by bond
• it is in Awaiting Approval status

If you click the icon next to the test case, you can also see that the test case has an upstream reference (the currently opened work item) and that there is an active Suspected flag (indicating that there have been modification both in the work item and in the test case).

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 between tracker items and any of the following:

• Other codeBeamer entities (other items or documents)
• External web resources

In contrast to references, associations do not have a defined value set, severity, or permissions.

All users who have access to a tracker item can create new item associations (in any item status). To add an association to a work item, follow the steps below:

1. Click Add Association on the Associations tab of a work item:

2. Select an association type from the drop-down list in the Association Type field:

The association type defines the relationship between the work item and the association.

3. Select a baseline in the Baseline field:

There are two options to select from:

• None (--): it means that the association will always point to the latest version available, irrespective of the time of creation of the association.
• Current HEAD: it means that the association will always point to the current HEAD version, that is, the latest version at the time of creation of the association.

4. Select any of the following options as applicable:

• Propagate suspects: if this option is selected, the association is marked as "Suspected" in case the associated item is modified. You can then decide whether the change in the associated item applies to your work item, and you can easily apply the changes in the associated item to the work item if necessary.
• Reverse direction: if this option is selected, the association is marked as "Suspected" in case the original work item (which contains the association) is modified. Note: this option belongs to the "Propagate suspects" feature, and you can only select this option if the "Propagate suspects" checkbox is checked.
• Bi-directional: if this option is selected, the association is marked as "Suspected" in case either the original work item or the associated item is modified. Note: this option belongs to the "Propagate suspects" feature, and you can only select this option if the "Propagate suspects" checkbox is checked. Also, you cannot select both "Reverse direction" and "Bi-directional" at the same time. If the checkbox for one of these options is checked, the other option is automatically deselected.
• Propagate Unresolved Item Dependencies: if this option is selected, the item's UID (Unresolved Item Dependencies) badge becomes active in case the item has unresolved (not resolved or closed) associations which are configured to use this setting. Note: this option cannot be used together with the "Reverse direction" option. If this option is selected, the "Reverse direction" option is made inactive. Also, if the "Propagate Unresolved Item Dependencies" option is selected, it is not possible to specify a baseline or version for the reference.

Note: The Propagate suspects option can only be used for associations between work items, dashboards, documents, and wiki pages. The Bi-directional option can only be applied between work items.

The Propagate Unresolved Item Dependencies option can only be applied between work items, except for test runs, reviews, and SCM related items.

5. Select an item to associate with the current work item:

You have the following options:

• From History: you can select an item from the list of items that you have recently worked with.
• From Search: you can search for an item in the system.
• URL: you create an association to an external link.

Propagate Suspects - Checking and Applying Changes and Clearing Suspicion

In case the "Propagate Suspects" option (with or without any of its sub-options) is specified for an association, changes in the associated item (and/or in the original work item) will be displayed when you open the item:

The direction of the arrow displayed together with the "Suspected" badge can be the following:

• Upward arrow: indicates that an upstream reference has been modified.
• Downward arrow: indicates that a downstream reference has been modified.

To check the changes made in an association and/or to apply the changes to the work item (or the other way round), follow the steps below:

1. Click the badge next to the associated item:

2. Using the Apply buttons on the Merge tab, merge recent changes or any other differences between the two work items as applicable:

You can decide which way you want to merge changes: from the associated item to the work item or the other way round. Use the leftward and rightward arrows in the Apply fields to merge changes as applicable.

Note: You can easily apply all changes from one item to the other at the same time by using one of the Apply arrow buttons in the top row.

Note: This tab displays all differences between the two items not only the fields which have been modified now and which triggered the "Suspected" badge.

If the Show different fields only option is selected (top right-hand corner), the system only displays the fields where the values are different in the two items. If this option is not selected, all the fields of the items are displayed (including empty fields).

In case the Omit Merge option is set for any field in the tracker (see section "Setting Default Reference Settings per Field"), changes made in that field will be listed under "Fields not merged automatically" on the Merge tab:

To clear the suspicions without merging any changes, click the Clear Suspected checkbox in the top left-hand corner.

To check the changes in the associated item which triggered the "Suspected" badge, click the Changes tab. To check the changes made in the original work item, go to the Derived Item Changes tab:

3. When you are finished merging changes, click Save to apply the changes.

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