You are not logged in. Click here to log in.

codeBeamer ALM

Search In Project

Search inClear

Issue Field Value Dependencies / Reference Dependencies



If you have parent/child hierarchies of configuration items or issues, you can now define dependencies between parent field values and the appropriate child field values (recursively). If, for example, you wish to ensure that a parent issue is not closed until all the child-issues (children) are closed, then this dependency can be managed using one of the distribution rules defined in this document. Similarly if you wish to define the parent issue's "Spent Hours" as the sum of the children's "Spent Hours" you can define this aggregation rule, too.

Parent field value updates can be distributed to children (recursively) and child field values can be aggregated into parent field values (recursively).

This is controlled in the distribution and aggregation rules shown in Category/TrackerCustomizeFields for each applicable field:

The set of applicable distribution and aggregation rules for a field depends upon the field and its type.

Standard Distribution Rules

Rule Description Applicable for
Set Set child field value to parent field value All fields
Default Set child field value to parent field value, but only if the child field is empty All fields
Least Set child field value to the least of parent and child field value All fields
Greatest Set child field value to the greatest of parent and child field value All fields
Fraction Set each child field value to a fraction of the parent field value Numeric fields
Subset Remove all child field values that are not also parent field values Multiple choice fields
Superset Add missing parent field values to the child field values Multiple choice fields
Close recursively Upon close of a parent, also close all children recursively Status
Close restricted Deny closing a parent, as long as not all children have been closed Status

Standard Aggregation Rules

Rule Description Applicable for
Minimum Set parent field value to the minimum of all child field values All fields
Maximum Set parent field value to the maximum of all child field values All fields
Sum/Total Set parent field value to the sum/total of all child field values Numeric fields
Average Set parent field value to the average of all child field values Numeric fields
Union Set parent field value to the union of all child field values (all distinct field values that appear in any child) Multiple choice fields
Intersection Set parent field value to the intersection of all child field values (all common field values that appear in every child) Multiple choice fields
Mean status Set parent status to a mean/average status of all children Status
Close upwards Close the parent, after the last child has been closed Status

A field can have no rules at all, either an aggregation rule or a distribution rule, or both.

A field with an aggregation rule, but without a distribution rule, will only be editable as long as the item/issue doesn’t have children.

As soon as children exist, an aggregated field without a distribution rule will become read-only.

For static choice fields: Minimum, Maximum, Least and Greatest will be determined according to the order of field choice values, as defined via Category/TrackerCustomizeChoice Lists .

If the internal order of choice values is logically descending (like the standard CodeBeamer Severity values), in order for an aggregated field to show the logically highest field value, the aggregation rule must be Minimum.

Recommended Combinations of Distribution and Aggregation Rules

If a field has both an aggregation rule and a distribution rule, care must be taken that both rules do not conflict.

Choose the aggregation rule first and then decide which distribution rule (if any) is appropriate.

Distribution rule Aggregation rule Effect on changing the parent value
Set Any, except Sum/Total Overwrites child values with parent value
Default -- Overwrites empty child values with parent value
Least Maximum No child value may be larger than parent value, so if a parent value is reduced, if a child value used to exceed the new parent value, the child's value is now set to the new parent value. Subsequent increases in the parent value have no effect on child values.
Greatest Minimum No child value may be smaller than parent value. Increasing the parent value also increases the child values that used to be lower than this new parent value. Decreasing the parent value has no effect on child values.
Fraction Sum/Total Changing the parent value will set the child values to “Parent value/number of children”
Subset Union All child values must be a subset of the parent value. Removing a parent value will also remove that value from all child value lists. Adding a new parent value has no effect on child values.
Superset Intersection All parent values must also be contained in the child value lists. So adding a parent value will also add that value to all child value lists. Removing a parent value has no effect on child values.
Close recursively Close upwards If all children are closed, the parent should also be closed. So closing the parent will also close all children. State transitions other than close are neither distributed nor aggregated.
Close recursively Minimum Similar to above, but child state transitions are aggregated into parent state transitions (including close)

These aggregation and distribution rule recommendations don't have to be followed, but the resulting effect may be difficult to predict if the suggestions are ignored.

For new trackers, the recommended aggregation and distribution rules will be placed by default with the corresponding fields. In existing trackers, the distribution and aggregation functions are available, but there is no automatic rule setting. The rules will be implemented only on new issues.

Examples

Numeric Field Type Examples:

Aggregation Rule Distribution Rule Change Result
Maximum -- Child values (1, 3, 5, 7) ↑ to (1, 3, 5, 8) Parent Value changes from 7 to 8
Maximum Least Parent value changes from 8 to 7 child value changes from 8 to 7

Set or Choice Field Examples:

Aggregation Rule Distribution Rule Change Result
Union Subset Child Value sets change from (1,2,3) & (3,4,5) to (1,2,3) and (4,5,6) Parent Value sets change from (1,2,3,4,5) to (1,2,3,4,5,6)
Intersection Superset Child Value sets change from (1,2,3) & (2,3,4) to (1,2) and (1,4) Parent Value set changes from (2,3) to (1)


Dependencies between different fields of the same item (Cascading fields)

Besides the dependencies between the same field of parent and child items in a tracker, which are controlled via the field's Aggregation and Distribution rules, CodeBeamer (since CB-7.0) also allows to define dependencies between different Choice/Country/Language/Reference fields (of the same item).

Static field value dependencies

E.g. The (values of the) Language field of a Contact should depend on (the values of the) Country field:


After selecting the Country field from the dropdown list and clicking on the 'OK' button the "depends on Country" link is displayed in Layout and Content of the Language field:




To define the actual/allowed Country/Language field value combinations, click on the "depends on Country" link. In the popup dialog, you can then define the allowed value combinations for the combined fields by clicking on the 'Add static dependency' link:





E.g. English is spoken in any country, the official language in Germany and Austria is German, and in Switzerland the official languages are German, French and Italian:





If you now create or edit a Contact, the available values for Language will depend on the selected Country, e.g. for Switzerland:




If the field (e.g. Country), where the current field's values depend on, contains multiple values, e.g. Germany and Switzerland, then the allowed values for the dependent field (e.g. Language) are those common values, that are allowed for all of the super values (intersection), e.g. English and German.

If you want to allow the union of allowed values instead, you have to check the appropriate checkbox in the dependency configuration (only CB-9.3 and newer):



Now the allowed values are the union of those values, that are allowed for any of the super values.
E.g. for Country Germany and Switzerland the allowed Language would be any language allowed for Germany and Switzerland: English, German, French and Italian.

Field dependency chains can be of any length, e.g. Field C depends on field B, which depends on field A.

On the GUI, dependent/cascading fields should be placed together, in the inverse dependency order: Dependent fields after the fields they depend on.

Reference field value dependencies between work/configuration items

Since CB-7.7.1, CodeBeamer also allows to define dependencies between work/configuration item reference fields, based on relations of the underlying tracker(s). There are two cases:

  • the reference items are in the same tracker and the items are in parent-child relationship
  • the reference items are in different trackers and there is a relation between the trackers via the Subject reference field
Dependency with parent-child relationship

E.g. there are countries and languages defined in a tracker in parent-child relationship, so the parent items are countries and the child items are languages and they are defined in the same tracker. Some example items in this Language Usage tracker could look like this:



Let's choose an other tracker where we can define the Country and Language choice fields, for example the Team tracker. A team will have a country and we define allowed languages for the team depending on the country of the team. The Country and Language fields are choice fields, both are referring to items from the Language Usage tracker:




After defining the Country and Language fields and we set the Language field to depend on Country the field configuration looks like this:



Now if we click on the "depends on Country" link then there is a new selector for reference dependencies, in addition to the static field value dependency link explained earlier.




This selector lists all source trackers for the "Depends On" field (in our example, there is only one: Language Usage). If there is only one source tracker, then a dependency for that will be automatically configured.

If you select a source tracker, a new entry will be added to the dependencies:




That new entry allows to select one or more constraints for the dependent field (Language in our example).

These constraints are the defined relations between the selected source tracker of the Depends On field and the possible source trackers of the dependent field (in our example there is only one: Language Usage).


The resulting reference field value dependency reads as:

  • If there is a selected Country item of the Language Usage tracker,
  • then only those Language item(s) are the allowed which are the children of the selected Country item, so the allowed values have the selected Country as their parent
Reference based dependency

In this example the countries and languages are defined in two different trackers and we have a relation via the Subject field from the Language to the Country tracker.

The field configuration of the Subject field in the Language tracker looks like this:



As in the previous example a team will have a country and we define allowed languages for the team depending on the country of the team. We can define the Country and Language choice fields as follows:



The Language field depends on the Country field:



If you look at the (extract of) the Tracker Class Diagram:

you will see that there is a relation between Language and Country via the reference field Subject.


Now if we browse the field configuration of the Team tracker click on the "depends on Country" link of the Language field then there is the "Add reference dependency" selector in the Field Dependencies dialog.



If you select a source tracker (Country in our example), a new entry will be added to the dependencies:



If there is only one source tracker, then a dependency for that will be automatically configured.


The resulting reference field value dependency reads as:

  • If the selected Country is an item of the Country tracker,
  • then only those Language item(s) are the allowed which refer to the selected Country via their Subject reference field.


If there are multiple possible source trackers for the Depends On field, then you should define constraints for each of them.