Overview

With the Microsoft Word import functionality you are able to import work items into your trackers.

Content of the document

The Word document should be structured using Word styles: after the import the heading styles will be the summaries of the work items, the paragraphs after the headings with normal styles will be the descriptions. The different levels of heading styles will make the parent-child relation between the work items.

Example: at the image you can see a part of a document, Transmission has Heading 1 style, Transmission TC and Default: Continuously variable has Heading 2, Minimum Torque has Heading 3.

After import, we will have the following work item tree structure:

Import screen

codebeamer has a general import screen, Import menu item is available in the More menu of the action bar of the tracker home page (table view or document view).

Select Microsoft Word and click to Attach a file... or drag and drop the file into the area to upload document. After the uploading will be finished, click on Next to navigate to the Preview screen.

Note: importing from Word is not possible if the current tracker has some mandatory fields beyond the Summary and Description fields. In this case a warning appears and it is not able to click on Next button. You can modify the Field settings of the tracker or begin import from another tracker.

Preview screen

The next page is the Preview screen where you can see the preview of the work item structure and content and furthermore you can filter and set the work items and define other import rules.

Part of the Preview screen:

• On the left side you can see the work item structure (parent-child relation) in a tree. After the summary of the work item, you can see the name of the Word heading styles in parenthesis.
• In the center pane you can find a Document View-like list of the to be imported work items.
• On the right side you can define Import rules using different kind of conditions, and see a Statistics area and the control buttons.

Define Import rules

You can define Import rules with specific actions and conditions. The rules are for what you would like to do with the work items if the defined conditions are met. As default you get the following rule which means, that all of the items in the document will be imported into the current tracker.:

You can modify the default rule, and also you can add more rules (+ button below the default rule) or delete an existing non-default rule (X button on the top right corner of the rule). If you are ready with setting the rules, click on Preview button to see which work item will be applied for which action according to the rules and their conditions. The conditions of the several rules can be overlapped, in this case always the action of the latest rule will be applied to the work item.

A rule has the following sections:

• Action selector
• Work item filter selector
• Logical operator selector between the conditions (AND or OR)
• Conditions

Action selector

Available rule actions are the followings:

• Import into the current tracker: the work items will be imported into the current tracker as "normal" work items (with no Information or Folder meanings)
• Import into the current tracker as...: this action is displaying only if the current tracker has Category field with Information or Folder meaning options. Selecting this action, work items will be imported into the current tracker as Information or Folder.
• Ignore: items will not be imported.
• Attach to parent: if work item has a parent item, the item will not be imported as an individual work item, but the Summary and Description will be concatenated to its parent item. If work item has no parent, this action will be omitted and it will be imported as an individual work item.
• Import into...: you can import work items into another tracker within the current project, the available trackers (trackers with "Add new item" permission for the current user) are shown in the list. It is not able to select trackers which has mandatory fields beyond Summary and Description fields, these trackers are listed as gray colour.

Work item filter selector

You can define where (in which work item branch or in the whole document) the rule will be applied. In the list you can find only the work items which has child items. You can also select multiple work items.

Logical operator selector

Two options available:

• if all conditions are met: the rule is applied if all the conditions below are met (the logical operator between the conditions is AND).
• if any conditions are met: the rule is applied if any the conditions below are met (the logical operator between the conditions is OR).

Conditions

You can select several kinds of conditions. The condition types are the followings:

• has the following style: if selected, a style selector appears next to the condition type selector. Condition will be met if the work item has one of the selected Word styles.
• no condition: if selected, condition will be always met.
• contains/contains (case-insensitive): if selected, condition will be met if the summary or the description of the work item contains the entered word (case-sensitively or case-insensitively)
• does not contain/does not contain (case-insensitive): if selected, condition will be met if the summary or the description of the work item does not contain the entered word (case-sensitively or case-insensitively)
• contains whole word/contains whole word (case-insensitive): if selected, condition will be met if the summary or the description of the work item contains the entered word as a whole word (case-sensitively or case-insensitively)
• match regex/match regex (case-insensitive): if selected, condition will be met if the entered regular expression matches for the summary or description of the work item (case-sensitively or case-insensitively). More about regular expressions here.

If you would like to add more conditions to the rule, click on + Add new Condition. For remove a condition, click on the X button next to the condition.

Overwrite rules

You are able to overwrite the actions for individual work items. The controls you can use:

• In the center pane, before every work item, there is a switch, clicking on this you can toggle importation (Import into current tracker or Ignore). If switched off, the section will be gray and this work item will not be imported.
• In the center pane after the summary there is a context menu, clicking on this, the menu shows all the actions you can set in a rule.
• In the left section, the tree has also a context menu with the actions, use right click mouse button on a work item to open the context menu.

If rules were applied before and you try to set actions for individual work item, a warning appears, which is about it can overwrite the set rule actions. Similar warning appears if you set actions for work items individually and after that you apply some rules.

Rules Example

We have a document with Tasks, Requirements and Test Cases. Basically we would like all items to be imported into the Task tracker, except:

• if one of the item's descriptions contains "should have" or "must have" expression, than these items should be imported into the Customer Requirements Specifications tracker.
• if item contains "test case" expression as whole word (in summary or in description) and this is in the Transmission section of the document, these items should be imported into the Test Cases tracker.

Start import from the Tasks tracker, upload document and click on Next. Now you can see the Preview screen and can set the rules.

First rule should be the default rule:

Click on the big + sign to add the second rule for importing into the Customer Requirements Specification tracker and set as follows:

Alternatively you can use only one condition for using match regex option and the following regular expression:

Add a new third rule for importing into the Test Cases tracker and set as follows:

Click on the Preview button, you can see in the Statistics box, how many items will be imported into which tracker. You can check also in the center pane which item will be imported and into which tracker.

Click on Save to import items.

Import work items

If you are ready in the Preview screen (you set desired rules / set actions for work items individually), click on Save button to finish importing. The page is navigated back to the home page of the trackers, and an information dialog shows, how many work items are imported. Work items will be created according to their actions (import to the current tracker, import into another tracker, etc.). Parent-child relation also remains if work items imported into a common tracker.

If child elements are imported into another tracker, a "depends on" type association will be created between the work items. Furthermore if some fields of the tracker of the child item can accept work items from the tracker of the parent item, it will be also filled out (e.g. if parent item is imported into Tasks tracker, its child item imported into Test Cases tracker, the Verifies field of the child item will contain the parent item, because Verifies field can accept work item from Tasks tracker).

Troubleshooting

How to fix if a Word import fails with an error message?

See: How to fix if a Word import fails with an error message?

What if my Word style does not appear in the style selector of the Word import?

As described earlier here: the Heading1 / Heading2 etc... styles in the Word document are used to split the Word document into parts: the paragraph with a Heading style will be used as name of the new Work Items, and any paragraphs between the Heading styles are imported as the "description" of the Work items.

The custom Word styles which are based on the "Heading X" style in Word as Heading styles: these paragraphs will be imported as Name of the Work item too.

So if you have a custom Word style which does not appear on the Word import GUI, but you want to use it as Name of the Work items then you need to modify that Word style in Word to be "based on" a "Heading X" style.

The following video illustrates how to do that:

Inconsistent Line Spacing After Import and Export to MS Word Through a Template

If an exported Word document has inconsistent line spacing behavior when pressing ENTER or SHIFT+ENTER, as in the following picture:

Ensure that Word uses the default Word Normal template with no styling customizations. To reset the Word Normal template to its default state:

1. Close all MS Word documents and all applications that are using MS Word.
2. Open File Explorer on your system.
3. Navigate to C:\Users\<user name>\AppData\Roaming\Microsoft\Templates
4. Locate the Normal.dotm file.
5. Rename it to Normal_backup.dotm
6. Launch MS Word.
   • A default and non-customized version of Normal.dotm is recreated automatically.

• Word applies the same text style everywhere in the document. To ensure consistency, PTC recommends selecting the Normal style. For detailed steps on how to apply a text style, see the Apply styles Microsoft guide.

See the PTC Support article www.ptc.com/en/support/article/CS419606 for detailed information.

How to import WMF/EMF content

How to importing WMF and EMF content from Word