Initializing fields of New Downstream references

The function Create Downstream Reference is available in CodeBeamer for some years now.

E.g. For a Requirement you can create a Create Downstrean Reference in the Test Cases tracker:

Copy Attachments

From codeBeamer 9.4.0 you have the ability to copy attachment from the source item to the Downstream Reference Item.

Check the User Preferences "Copy Attachment when creating a New Referring Item" option:

If you select Always ask, a confirm overlay will appear during Create Downstream Reference, where you can decide if you would like to copy the attachments from the source item. Selecting "Automatically copy" or "Do not copy" will copy / not copy the attachements without asking.

Initializing fields of New Downstream references

The function is based on the defined relations between the trackers (via reference fields):




The example Tracker Dependency Diagram above shows references to System Requirement Specifications from

• User Stories (Requirements),
• Change Requests (Subject),
• Bugs (Subject),
• Tasks (Subject),
• Test Cases (Verifies)
• and also System Requirement Specifications itself (as Template).

For each (downstream) reference, you will find an appropriate entry in the New Referring Item menu of the referenced target tracker (see first screenshot).


Until CB-7.7.0, only the reference field (e.g. Verifies (subject)), that establishes the relation between the new item and the item where New Referring Item was called from, was automatically preset, along with:

• Assigned to
• and Release.

But starting with CB-7.7.1, you can define rules, how to initialize other fields of the New Referring Item with values taken from fields of the referenced item,

• in a configuration file named my-NewReferringItem.properties (please create it if does not exist)
• in ~/CB-.../tomcat/webapps/cb/WEB-INF/classes/.

The file my-NewReferringItem.properties is a Java Properties file.

The key of each entry is a String of the form: Tracker[@Project].references->Tracker[@Project]

that identifies:

• a Tracker, identified either by tracker name or tracker type name (stereotype):
  • Bug
  • Change Request
  • Component
  • Contact
  • Platform
  • Release
  • Requirement
  • Risk
  • Task
  • Team
  • Testcase
  • Testconf
  • Testset
  • Testrun
  • Usecase
  • User Story
• Since CB-8.0, you can also use these tracker type names (stereotypes):
  • Item, as a placeholder for any type of work/configuration item
  • Issue, as a placeholder for any type of work items
  • Configuration Item, as a placeholder for any type of configuration items
• optionally in (@) the Project with the specified project name or in a project with the specified category,
• that references (via a reference field, identified by name or by internal attribute/property name, or since CB-8.0: *)
• another Tracker (identified by tracker name or tracker type name)
• in (@) the Project with the specified project name or in a project with the specified category (optional).

If a Tracker is specified without a Project, then this means trackers with this name or stereotype in any project.

Examples for Tracker:

Examples for: "A new Testcase referring to a System Requirement Specification as Verifies (subjects)":

• Test\ Cases@Test.Verifies->System\ Requirement\ Specifications@Test
  This only applies for creating new items in the Test Cases tracker of the Test project, referring to items of the System Requirement Specifications tracker (in the same project) via the reference field named Verifies (subjects).
• Test\ Cases.Verifies->System\ Requirement\ Specifications
  This applies for creating new items in the Test Cases tracker of any project, referring to items of the System Requirement Specifications tracker (in any project) via the reference field named Verifies (subjects).
• Testcase.subjects->Requirement
  This is the most generic form. It applies for all trackers of type Testcase (in any project), referring to items of trackers of type Requirement (in any project) via the subjects field.

Blanks within the tracker/project/field names must be escaped, e.g. Customer Requirement Specification must be written as: Customer\ Requirement\ Specification.

Configurations via project names, tracker names and/or reference field names have precedence over configurations via project categories, tracker types and/or reference field property names.

If multiple configurations are applicable, they are applied in their order of precedence.

If a field has a default value, this default value will always have precedence over any setting in my-NewReferringItem.properties!


The value of each entry in my-NewReferringItem.properties is a list of field initializations (Field = value), separated by semicolon (;):

• Field identifies a field in the item to initialize (left Tracker in the identifier/key) and can be either
  • the field property/attribute name (preferred)
  • or the field label, but only,
    • if the label only consists of alphanumeric characters ([A-Z],[a-z],[0-9]), ‘$‘(dollar sign) and ‘_‘ (underscore),
    • does not start with digits ([0-9])
    • and does not contain HTML markup
    • e.g. Color is allowed, but Background color, Best.-Nr., Estimated<br/>Effort or <b>v</b>_max (v_max) are not allowed as field identifiers
  • or the RESTful field name (lower camel case of field label, with all HMTL markup and not allowed characters removed)
    • e.g. Color, Background color, Best.-Nr., Estimated<br/>Effort or <b>v</b>_max can be referenced as color, backgroundColor, bestNr, estimatedEffort and vmax
• The value is a Unified Expression Language (EL) expression, that defines the initialization value for this field (see Computed Fields).
  • Within the value expression you can refer to (the value) of fields from the referenced item (the Tracker after -> in the identifier/key) (see the rules for Field identifiers above).
  • Semicolons (;) within a value expression must be escaped as \;
  • Backslashes (\) within the value expression must be escaped as

    \\

    , e.g. a Wiki Markup Newline (

    \\

    ) must be written as (

    \\\\

    )

Default NewReferringItem.properties:

Item.*->Item: \
	versions   = versions; \
	assignedTo = assignedTo

Requirement.subjects->Requirement: \
	categories    = categories; \
	namedPriority = namedPriority; \
	severities    = severities; \
	name          = name; \
	description   = fn:concat("Refinement of: \\\\[<<description>>|ISSUE:", id, "]"); \
	Color         = customField[0]; \
	Risk          = choiceList[1]

Testcase.subjects->Requirement: \
	categories    = categories.{category|category.name}; \
	namedPriority = namedPriority; \
	name          = fn:concat("Test ", name); \
	description   = fn:concat("This is to be tested: \\\\[<<description>>|ISSUE:", id, "]");

For better readability, definitions in the above example have been broken up into multiple lines. Therefore the \ at the end of each line is necessary, to indicate that this definition continues on the next line.

That way, it is also more obvious, that

• the target fields of the value assignments (field = value) belong to the left tracker in the definition key,
• and (source) fields referenced in the value expression belong to the tracker specified right of -> in the definition key.

Caution: Copying static choice field options between trackers of different types will only work, if the choice option ids are identical in both trackers.

So only assign choice options directly, if you are sure that their ids are identical in source and target tracker, e.g. for namedPriority:

Testcase.subjects->Requirement: \
    namedPriority = namedPriority;

Otherwise you should assign choice options by name:

Testcase.subjects->Requirement:\
    categories = categories.{category|category.name};

So a New Referring Item in the Test Cases tracker, for the System Requirement Specification in the first screenshot would be initialized as:





Since CB-8.0, the initialization of assignedTo and versions is also done via this mechanism and not longer hardcoded.
This allows overriding the intialization.

E.g. my-NewReferringItem.properties:

System\ Requirement\ Specifications.subjects->Customer\ Requirement\ Specifications:\
        assignedTo = null

will override default NewReferringItem.properties:

Item.*->Item: \
	...
	assignedTo = assignedTo

Please note: To override an initialization of a field, to not initialize this field, assign the value null.