Adding item mapping rules

You can add item mapping rules to specify the fields to copy to new requirements created from existing requirements. For example, you can create a rule for creating functional requirements from business requirements or functional requirements from other functional requirements. You can also indicate if the requirements should be linked and if new requirements are added to the same folders as source requirements.

Note:  You can only add rules for creating requirements from requirements and not other item types. Default rules already exist for all other item types. See Default item mapping rules. Edit an existing rule to change the mappings and other information. See Editing item mapping rules. You can only add one rule with the same source and new requirement types.

Keep the following in mind:

  • You can map pop-up menu, integer, and date/time fields to text fields. If a text field's limit is exceeded, the data is truncated to the field limit. To map two pop-up menu fields, the fields must use the same value list.
  • You can map multiple fields to one field in new requirements. For example, you can map the source requirement Summary and Source fields to the Description field to include the information from both source requirement fields in the new requirement's Description.
  • You can select Folders as the field to copy to a new requirement. Folders can only be mapped to text fields. If the Folders field is mapped to a single-line text field, a list of folder names is copied to the new item. If the Folders field is mapped to a multi-line text field, a list of folder paths is copied to the new requirement.
  • You can map decimal fields to integer fields. When a requirement is created from another requirement and the Add Requirement dialog box opens, users must change the decimal value copied into the integer field before saving the new requirement.
  • You can map calculated custom fields as the source field to copy to new requirements, but these fields cannot be selected as the field to be populated.

1. Choose Tools > Administration > Item Mapping Rules.

The Item Mapping Rules dialog box opens.

2. Click Add.

The Add Item Mapping Rule dialog box opens.

3. Select the requirement type to create and the source requirement type.

4. To edit a default field mapping, select it and make any changes.

The following fields are mapped between source and new requirements by default:

  • Summary—The summary in a new requirement is prepended with the tag from the source requirement, as indicated by the %TAGNM% field code in the Prepend Text column.
  • Description
  • Custom fields—All custom fields are copied to new requirements. Any requirement custom fields added to the project after the rule is created must be manually added to the rule. You can also edit a rule and click Restore Default Values to add all custom fields to the Field Mappings list Keep in mind that any mappings previously added are replaced. See Editing item mapping rules.

5. To add a mapping, click Add.

A new row is added to the Field Mappings list.

  • Select a field to copy from the Copy Field list. This field value in the source requirement is copied to the field it is mapped to in the new requirement.

Note:  You must select a field to copy before setting other mapping options.

  • Select a field to map the source field to from the to Field list. This field in the new requirement is populated with the value from the source requirement field.
  • Optionally enter text or field codes in the Prepend Text and Append Text fields. You can only prepend and append text to values that are mapped to text fields. Click the Select Field button to select from a list of available field codes.

6. To delete a mapping, select it and click Delete. To delete all mappings, click Delete All.

7. Click Restore Default Values to restore the default field mappings.

8. Select Add the requirement to the same folders as the source requirement to add new requirements to the same folders as the source requirements.

If the user creating the new requirement does not have permission to work with the folders or they are locked, the item cannot be added to the same folders as the source requirement.

9. Select Require adding new requirements to a document to require users to add new requirements to a document.

If this option is selected, users are prompted to select a document in the Select Requirement Document dialog box before adding a new requirement. New requirements are appended to the end of the selected document. When the new requirement is saved, the document opens with the new requirement, making it easier to find.

Note:  If this option is selected, users can only create requirements based on this rule if the Add Requirements to Requirement Documents security command is enabled for their security group. See Requirement documents security commands.

10. Select a Link definition to use when a new requirement is created from an existing requirement. The list includes all link definitions that allow linking the two requirement types.

Select Prompt user before adding link to prompt users to create a link when creating new requirements from existing requirements. If this option is not selected, the link is automatically created. The selected link definition is always used. See Working with related items.

11. Select a mapping and click Top, Move Up, Move Down, or Bottom to organize the field order.

If multiple fields are mapped to the same field in a new requirement, values are added in the order displayed in the Field Mappings list.

12. Click OK to save the changes.