Editing item mapping rules

You can edit an item mapping rule to change fields copied from the source item to the new item, text to prepend or append to copied field values, and linking or folder options.

Keep the following in mind:

• You can map item fields of the same type. For example, you can map test run text fields to issue text fields. You can also 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 items. For example, you can map the test run Summary and Steps fields to the issue Description field to include the information from both test run fields in the issue Description.
• You can select Folders as the field to copy to a new item. 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 item.
• You can map decimal fields to integer fields. When an item is created from another item and the Add dialog box opens, users must change the decimal value copied into the integer field before saving the new item. When an item is generated from an item and automatically added to the project, the decimal value copied to the integer field is accepted. If the generated item is edited, users are notified that the decimal value is invalid and must be changed before the changes can be saved.
• You can map calculated custom fields as the source field to copy to new items, 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. Select a rule and click Edit.

The rule dialog box opens.

3. If the rule is for creating requirements from requirements, optionally change the requirement type to create and the source requirement type.

4. To add a field mapping to indicate the fields to copy values to and from, click Add.

A new row is added to the Field Mappings list.

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

• Select a field to map the source field to from the to Field list. This field in the new item is populated with the value from the source item 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 to select from a list of available field codes.

5. To change an existing field mapping, select it and make any changes.

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. See Default item mapping rules.

8. Select a rule 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 item, values are added in the order displayed in the Field Mappings list.

9. Select a copy option if available for the rule.

• Create Requirement from Issue rule—Copy all issue reported by description fields to requirement description copies information from the issue Detail: Found by mini tab to the requirement Description. If you map an issue reported by field with multiple records, only fields from the first record are used if this option is not selected.
• Create Issue from Test Run rule—Copy test run problems statements to issue description copies information from the test run Steps tab to the issue Description.

10. Select Add the item to the same folders option to add new items to the same folders as the source items.

After the new item is saved, users can open the folder or remove the item from the folder on the Folders tab. If the user creating the new item 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 item. When creating issues from test runs, issues are not added to test run suite folders because only test runs are allowed in them. This option is not available for generating test cases from requirements, generating test runs from test cases, or inserting shared steps in test cases.

11. If the rule is for creating requirements from requirements, 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.

12. Select a Link definition to use when a new item is created from an existing item. The list includes all link definitions that allow linking the two item types. If you select a parent/child definition, select the item type to use as the parent item in the link. If the link definition only allows one of the item types as the parent, it is automatically selected and cannot be changed. This option is not available for generating test runs from test cases or inserting shared steps in test cases.

Select Prompt user before adding link to prompt users to create a link when creating new items from existing items. If this option is not selected, the link is automatically created using the default link definition. See Working with Related Items.

13. Click OK to save the changes.