Importing Microsoft Word Documents

The Import from Word (or "Word Import") feature enables you to take existing content of specifications, test cases, etc. that has been written in a Word document, and convert it into a Polarion LiveDoc Document, enabling your organization to take advantage of Polarion's process automation and management capabilities, while retaining for document authors the familiarity and ease of use of a simple desktop-based office document. By bringing the content of your Word documents into Polarion, your authors give up very little in terms of how they write and format content, and your organization gains much in terms of efficient and controlled process, full-lifecycle traceability, transparency, and team collaboration and communication. (Remember that after a Word document is imported, you can always export it back to its original format to work on it offline, or enable others to do so. See Sharing Documents with Word Round-trip.)

Let's take a moment for a brief overview of this extremely powerful functionality. A typical (but by no means the only) use case is to bring existing requirements specifications into Polarion. In so doing, you can have Polarion automatically differentiate between document content that is just general information, and content that should be recognized as requirement type artifacts (i.e. requirement type Work Items) which can be tracked, assigned, planned, managed with workflow, and linked for traceability across functional boundaries such as Quality Assurance and Development/Engineering.

This automatic recognition can be based on keywords in the document (words like "must", "should", "may"), or on styles defined and applied in the Word document (bullet, heading, and paragraph styles), or some combination of both of these. Keywords can also serve as triggers for actions specified in import rules and applied to recognized Work Items. For example, the word must in your document might the trigger for an action to set a value in the Severity field value to must have (values should be already defined in the project configuration). You define Work Item recognition rules using easy to understand graphical controls when you import a Word document into Polarion as a Live Document.

You can save any set of rules you define as an Import Configuration which you can then quickly apply to other documents when you import them, so you only need to define Work Item recognition rules for similar documents once. You can of course have multiple Import Configurations for different types of documents. For example, you might have one set of rules in an Import Configuration which you apply only when importing software requirements specifications, and another when importing functional requirements specifications, and yet another for test case specifications.

Important Compatibility Note

Word documents to be imported must be saved in Word 2007 (or higher) format. (With the .docx file extension.) The older .doc format is not supported.

By default, import file size is limited to 50 MB. (The limit is configurable in Administration.)

Custom Paragraph Styles in an Existing Word Document

If the default paragraph style of a Microsoft Word document is customized, it will not affect its appearance when imported into Polarion, but will be applied when the document is exported back into Word.

Launching Word Import

This section tells you how to begin importing a Word document. Subsequent sections in the chapter explain how to define rules to automatically recognize Work Items, set severity level and/or other data values from document content, and then work on the new LiveDoc Document after importing.

Documents can only be imported into an existing project. If you do not yet have a project created for your Documents, you should read about planning new projects and creating new projects before going further with Word import. You must have user permissions allowing you to create and save content in the project where you will import Word documents.

To begin importing a Word document:

  1. Open the project into which you want to import your Word document content.

  2. In Navigation, click on Documents and Pages. The topic's home page loads in your browser.

  3. In the toolbar at the top of the page, click the Create New button.

  4. In the Import section of the Create New dialog, click the clink labeled Word Document

  5. Choose an Import Configuration in the Configuration list. If no Import Configurations have been saved by you or other users, the only item in the list is Default. Use it for the current import. You will be able to define Work Item recognition rules and save them as a new Import Configuration later in the import process. (Import configurations enable you to reuse Work Item recognition rules when importing other Word documents.)

    Figure 15.1. Import Document Dialog

    Import Document Dialog

    Select a Word document in .docx format to import into Polarion

    If additional Import Configurations exist in the list, select any which you know to be applicable for documents of the kind you are importing. (Additional Import Configurations appear in the list only if a user has created and shared them, or the project template from which the project was instantiated provides some additional import configuration.)

  6. Click the Choose File button and use your file system navigation to select the Word document file you wish to import. The file format must be .docx.

  7. Click Next to upload the document and begin the import process.

    When your document is uploaded, Polarion converts it to a LiveDoc Document and displays a Preview. Note that nothing is committed to the repository yet, and the import can be canceled using the Cancel Import link in the Preview.

    The Preview contains a panel where you can optionally specify a name (ID) and title, specify the Document type, select the destination space, and define and save rules that control the recognition of portions of the content as Polarion-managed Work Items (see screenshot in the next section.)

  8. In the rules panel, optionally change the default Document name and title in the Name and Title fields, respectively, at the top of the panel.

  9. If your project is configured to support Document types, you can optionally select a different Document type in the Type field. (If types are not configured, the field is not present).

  10. In the Space list, select the Wiki space where you want the LiveDoc Document to reside (if you want a different space than the one selected by default).

If you don't want to define automatic Work Item recognition rules at this time, you can remove any existing rules in the Preview, and check the preview of the LiveDoc Document to make sure that nothing is marked as a Work Item, and then click the Import button to finish the import process and create the new Document. You can then work on this document and mark Work Items manually while editing the Polarion document.

If you do want to have content recognized and marked as Work Items on import, you now need to define Work Item import rules so that Polarion will automatically create Work Items in your new LiveDoc Document when you complete the import process.

Note

If the project is configured to support Document workflow, then after the import operation, the Status field of the new LiveDoc Document will be set to the configured initial Status value, and any configured initial workflow action will be executed.

For example, if the initial configured Status value is "Draft", the new Document will have that status, even if the source Document was not a draft, but a finished specification.

Configuring Automatic Work Item Recognition

This section explains how to set up automatic Work Item recognition (as mentioned in the previous section). This feature enables Polarion to create Work Items based on content in the original Word document according to Work Item import rules you specify during the Preview stage of the import process. It is assumed that you have successfully imported a Word document and are now seeing the Preview:

Figure 15.2. Imported Document Preview

Imported Document Preview

Preview an imported Word document and define Work Item recognition rules which reflect in the preview.

Your goal is to have Polarion recognize that some content in the original Word document is just general text, while other content should be recognized as Work Items of some particular type - requirements or test cases, for example. While the Document is in Preview mode, you can experiment with the Work Item recognition rules without actually creating any Work Items in the repository.

Advance Preparation

Before you begin importing Word documents, there are several things to consider and set up.

  • Polarion project: you should already have a project set up in Polarion, and you should know what Work Item types are defined in the project's configuration.

  • Document Type: you should know whether your project configuration defines different types of Documents. If it does, you will be able to choose the type your imported content. If not, you should consider if you your project should be configured for different Document types before importing your content.

  • Work Item Type: Decide which Work Item type(s) you want to create in Polarion through the imported Word document.

  • Content-to-Work Item Strategy: Review the Word document and identify what elements should become Work Items after the document is imported. This is they key thing to successfully have Work Items recognized from your document. For more information, see the following section.

Preparing the Document

You should go through the Word document you plan to import and make sure you know what content should be managed as Work Items in Polarion after import.

Consider requirements as an example. What elements of your document should Polarion recognize and mark as Requirement type Work Items? Should it recognize some words? Should it recognize some paragraph or list item styles? Or whole sections under headings? Will you need to define just one simple Work Item Rule to achieve the recognition you want, or will you need a more complex rule, or multiple rules? While it's possible devise quite complex strategies that get very granular, you can actually achieve a great deal with fairly simple rules. For example, Polarion's default import configuration will recognize the words "must" and "should", it will mark paragraphs containing those words as Requirement type Work Items, and it will set the Severity level to "must have" or "should have" respectively. The project configuration must have the Requirement Work Item type and the severity levels defined. This configuration is standard in Polarion's project templates that support requirements management. So if you create a project based on such a template, and edit your Word document so that only the content of Requirements contains the words "must" and "should", you will achieve quite a usable result when you import the document and use the default Work Item Rule.

Another easy to implement strategy would be to make sure all requirements in your Word document have a particular style. For example, you might define paragraph style named "Requirement" and apply it to all paragraphs that should be recognized as Requirement type Work Items. Then when you import the document, create a Work Item Rule that specifies that elements in the document with that style applied to them should be recognized as Requirement.

Figure 15.3. Simple Style-based Rule

Simple Style-based Rule

A simple Work Item Rule that recognizes a style

Another possibility that is still fairly easy is to define a heading style named something like "Requirement H3" in addition to the paragraph style "Requirement". On import, you can create a multi-condition, yet still fairly simple rule that says to mark "Requirement 3" styled content as a Work Item, and include in the description any following paragraph styled with the "Requirement" style.

Figure 15.4. Multi-condition Style-based Rule

Multi-condition Style-based Rule

A rule to recognize a heading style and following paragraphs with a specified style

Suppose that you have a bullet list after a "Requirement" styled paragraph, and you also want to include the list in the Work Item description? Just add another condition to the rule that says to include paragraphs styled as list items which occur after a "Requirement 3" styled heading. This gives you a very powerful, but still fairly simple to define Work Item Rule.

Figure 15.5. Complex Style-Rule

Complex Style-Rule

A more complex rule that includes multiple element styles into the Work Item description.

TIP

Remember that in the import Preview, you can experiment with Rules and see what their effect will be before you finalize the import. The rules pane contains the Preview button in the lower left corner. Clicking this button show a preview of the Document with the current Work Item Rule(s) applied as they are currently set in the pane. You can continue experimenting with Work Item Rules until you are satisfied with the result.

Remember also that Work Item Rules can be saved as Import Configurations which can be used when importing Word Documents. To learn how to reuse an existing Import Configuration so that you do not need to specify Work Item rules for a document you are importing, see Using a Saved Import Configuration.

Defining a Simple Work Item Rule

A "simple" Work Item Rule is one using only basic options and specifying one or more conditions. A rule's components read like an instructional sentence...

"Mark paragraphs from [whole document/specific section] as [a Work Item of this type] if [any/all] of the conditions are met:"

...after which come one or more conditions: [contains words][words], [has style][style], [contains text matching regex (regular expression)][expression], to name a few examples of conditions.

Figure 15.6. A Simple Work Item Rule

A Simple Work Item Rule

Simple Work Item Rule with 2 conditions that will cause paragraphs anywhere in the document to be marked as a Requirement if they contain any of the word shown, or if they are a list item.

To define a simple Work Item Rule, specify:

  • Content source: In Mark paragraphs from, select the section(s) of the original document in which Polarion should apply rules to recognize Work Items. Select Document to have Polarion apply Work Item recognition rules in all sections.

  • Select the type of Work Item to be recognized in the content source. The list contains the Work Item types defined in the project configuration.

  • On the first conditions line, select a condition from the drop-down list of conditions. If your selection requires more input to complete the condition, an appropriate text, list, or other field will appear on the line. Fill in the additional information.

  • If you need another condition in this rule, select it in the drop-down list on the second conditions line and as before, fill in any additional information.

  • If you need more conditions, add new condition lines by clicking the icon. Fill in the data as needed. If you make a mistake, you can remove any condition line from the rule by clicking the icon at the end of the line.

If you need one or more additional rules to achieve the Work Item recognition you want, you can click the Add Work Item Rule button near the top of the rules pane. A new simple rule is added each time you click. Repeat the above steps for each simple rule you add.

Defining Advanced Option Rules

Each simple rule you define can optionally have Advanced options added to it to make it even more robust and selective. Advanced rule options are disabled by default. To enable these options for any rule, check the Show advanced options box. The rule panel expands to show the advanced options.

Advanced options fall into the following categories which appear as labeled sections in the rule panel:

  • Paragraph inclusion conditions: Here you can specify conditions for including paragraphs which follow an element marked as a Work Item according to the conditions in the simple rule. For example, suppose the simple rule specifies that elements styled as Heading 3 are to be recognized as Work Items. You would probably want the paragraphs that follow the heading included in the Work Item description, so you can specify one or more conditions under Include next paragraph to the Work Item description. You might specify paragraphs that have some style, and/or that are list items to include after the heading.

  • Actions: Here you can define actions which set the value of Work Item fields when document content is recognized as a Work Item according to the rule. Each rule's Advanced options contain one action by default. If you don't want it, you can remove it by clicking the X icon in the upper right corner of the action's panel. If you want more actions, you can click the Add button at the bottom of the actions section.

    Each action applies to a selected Work Item field (of recognized Work Items). Select the field in the Set field list. Depending on the field selected, an control appears which enables you to set the value of the selected field. The execute field enables you to specify whether the specified value will be set always, or conditionally. If conditionally, fields appear enabling you to define one or more conditions in a manner similar to conditions for other rule parameters.

  •  Additional options: Here you can opt to have the first paragraph of any block of content the rule marks as a Work Item imported as the title of the recognized Work Item. (The first paragraph of such a block might be a heading.) You can also specify what, if any, fields you want to appear at the beginning, and at the end of recognized Work Items in the online Document. You must specify the field ID in Fields at start and Fields at end. If you want the values of more than one field to appear at the start or end of recognized Work Items, specify multiple IDs separated by a comma (,) character.

See also: User Reference: Document Reference: Import Rules for Tables.

Import Work Items from Tables

Work Items can even be extracted from tables within the Word document being imported. You can target all the tables within a document or select only the sections, even sub-sections to include.

Multiple rules can be created to extract different Work Item types (Requirements, Tasks etc.) and Severity or Priority levels can also automatically be extracted.

In the example below, requirement keywords within a table are detected and assigned different Work Item severity levels using the advanced table rule options.

To Import Work Items from within Tables

  1. (Optional) To extract Work Items exclusively from tables within the document, close () the Mark paragraph from section.

  2. Click + Add Work Item Rule and select Mark Tables.

    Figure 15.7. Select "Mark Table"

    Select "Mark Table"

  3. Define the scope of the tables to include in the Mark tables from drop-down menu.

    (Clicking on Document will apply the rule to the entire document.)

    Figure 15.8. Define the Scope of Tables to Include

    Define the Scope of Tables to Include
  4. Select whether to invoke the rule if "any" or "all" the conditions are met.

  5. Select whether to apply to rule to "Whole Tables" or only the "Header Rows".

  6. Under Import Rows, select a Work Item type in the as drop down list.

    (Requirement, Test Case, Task etc. Options vary depending on the configuration.)

  7. Select the rule's behavior in the drop-down list.

    TIP

    Mouse over the option to view a tooltip describing what it does.

    Figure 15.9. Select a Rule Type

    Select a Rule Type
  8. Enter the condition details in the field that appears on the right.

    (If “contains text” is selected like the example above, enter the text that the rule should search for.)

    Figure 15.10. Define the Rule’s Search Parameters

    Define the Rule’s Search Parameters
  9. Click to add additional conditions.

    TIP

    To assign different Work Item attributes to each condition (i.e. Severity), rather than adding it here, create an entirely new rule by clicking “Add” after the initial rule is defined. (See optional "Step 13")

  10. Polarion will automatically detect the target area’s columns and try to match the text to existing Work Item definitions.

    Any Column headers that cannot be recognized can be assigned manually or excluded by leaving them as “not selected”.

    Figure 15.11. Map Columns to Fields

    Map Columns to Fields

    (Optional) Under “Show Advanced Options”, additional Work Item attributes (like Severity or Priority) can be set so that they are automatically defined while the file is being imported.

  11. (Optional) Check the “Show Advanced Options” box.

    The “Fields at start” and “Fields at end” can be customized to change what attributes appear at the beginning and end of the work item in the imported document.

    Figure 15.12. The “Fields at start” and “Fields at end” options

    The “Fields at start” and “Fields at end” options
  12. (Optional) Click Add then select an option in the “Set Field” to enter additional Work Item attributes like Severity or Priority.

    (What options are available can be customized by Administrators.)

  13. (Optional) The available options under the “To” field change depending on what was selected in “Set Field”.

    In this example, (and configuration), “Severity” is selected to convert table cells that contain “Should” to requirements with a Should Have severity level.

    Figure 15.13. Show Advanced Options – Define Severity

    Show Advanced Options – Define Severity
  14. (Optional) Select when the rule should be implemented in the “Execute” drop-down box. (Always by default.)

  15. Click Preview to see how the rule affects the document.

    REMINDER

    The document has not been imported yet. Clicking Preview will only display what the rule WILL convert when Importis clicked.

    This way, rules and rule combinations can be thoroughly tested without creating, then having to delete unwanted Work Items.

  16. Any table rows that do not have a Work Item rule applied to them are highlighted in red.

    Table rows that contain data that the rule(s) recognize are converted to work items that appear below the table.

  17. Check the “Replace Table with Imported Items” box to replace the table(s) with the extracted Work Items.

    (If left unchecked, the created Work Items will appear directly below the table they were detected in.)

    Figure 15.14. Detected Table Data

    Detected Table Data
  18. (Optional)Click Add above “Replace Table with Imported Items” to add another table rule.

    Figure 15.15. Add Another Table Rule

    Add Another Table Rule

    REMINDER

    Click to the right of + Add Work Item Rule to save the set of rules for later use.

  19. Click Import when satisfied that all the necessary information has been converted into Work Items.

Saving Work Item Rules for Reuse

Once you have defined a Work Item Rule (or a set of such rules) in the document Preview and verified that they cause Work Items to be marked correctly, you can save your definition as an Import Configuration that can be reused when importing similar documents in the future, eliminating the need to specify Work Item rules every time.

To save the rules currently defined in document Preview:

  1. In the rules pane, click and choose Save. The Save Import Configuration dialog appears.

  2. If you are saving rules to a new configuration, select Create new configuration and enter a name in the Name field.

  3. If you want to save your current rule definitions to overwrite an existing configuration, select Update existing configuration, and select which configuration you want to update from the list of existing configurations.

  4. Click Save to save the new or updated configuration. If you saved a new configuration, it now appears in the list of Import Configurations which users can select when importing Word documents.

Using a Saved Import Configuration

If you or a colleague have saved a set of Work Item Rules as an Import Configuration, and the content of the document you are importing conforms to the rules defined in it so that Work Item content will be correctly recognized, you do not need to define any rules when you preview the document after starting the import process. Rather, you can invoke a saved configuration and import the document according to its rules.

To reuse a saved Import Configuration:

  1. With the imported Word document in Preview mode, click () and choose Load.

  2. In the dialog, select the Import Configuration whose Work Item recognition rules you want to reuse for the current import operation.

  3. Optionally, click the Preview button and check the document preview to verify that the document's Work Items are marked as expected.

  4. Click the Import button to import the Word document reusing the selected Import Configuration.

See also: User Reference: Documents Reference: Managing Saved Import Configurations

Setting Severity from Document Content

Having the Work Item recognition process set the severity level of recognized Work Items automatically is commonly-needed, and is just one example of the actions that can be executed and applied to recognized Work Items during Work Item recognition. You can specify this in the Actions section of the Advanced options of a Work Item Rule. There, you can select the Severity field, and specify the conditions for setting a value for the field when a Work Item is recognized according to the rule. For more information, see Defining Advanced Option Rules.

Table of Contents

The import feature also imports Table of Contents (TOC) from the source document. The following points should be kept in mind:

  • Outline numbering is turned on by default, and the TOC of the resulting Document will contain outline numbers in the TOC.

  • If the source document contains a table of contents, a table of contents will be generated in the resulting Document during import. A manual TOC is replaced by an automatically generated and updated TOC in the Document. Up to five heading levels are recognized and rendered in the TOC of the Document. Properties of the original TOC are saved and used in any subsequent Word Round-trip export.

  • If the source document contains a TOC, the import preview shows how it will look in the Document after import. The TOC preview is updated when the import preview is updated. TOC items in the import preview are not clickable.

  • Headings that are recognized as Work Items do not appear in the Document TOC (in both import preview and the Document). If the source document contained a TOC but all headings are recognized as Work Items, then the Document TOC will be empty.

Documents With OLE Objects

Polarion can display OLE Object thumbnails during Word document import. However, some additional third-party image converter software must be installed and configured before you can import such Word documents. Please see the Administrator's Guide topic Configuring OLE Object Support.

Unsupported Content

If the source document contains images or other content in formats not supported by the import from Word and image conversion features, the document is imported into Polarion without the unsupported content. If your project administrator configures the wordImport.ignore.[CLASS] system property for the content type(s) in your Word documents, a placeholder image and/or text informing you of the omission is inserted into the Document at the same point where the original, unsupported content was in the original Word document. See the Administrator's Guide topic Advanced System Tuning: wordImport.ignore.[CLASS] for more information.