Sharing Documents Using Word Round-trip

Any Document, whether created in Polarion or imported from Word, can be exported to Word. The exported document can then be shared with others, or the Document author can work on the document off-line. After changes, the exported document can then be imported back to Polarion where the changes are incorporated into the online Document and the Document history is updated. This feature is called Word Round-trip.

When exporting the Document, you can control the level of change that anyone can make to the exported document.

TIP

You can prevent pages breaks from occurring within Work Items by enabling the No Page Break in the Document Presentation dialog, accessible in the Document Editor (click the Work Item type icon in the toolbar). When checked for any Work Item type, Polarion will attempt, as much as possible, not to have page breaks occur in Work Items in the exported Word document.

Warning

  • If the Document contained comments when it was exported, and the user of the exported round-trip document changes the text of existing comments, these changes are not imported back to Polarion. Round-trip document users should add new comments.

  • 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.

  • HTML and CSS styles inserted into a Wiki content block may not export correctly. To ensure that styles are exported as expected, only use the styles that are created by Polarion's document editor.

  • Polarion does not clean up HTML within a Wiki content block. If a block contains invalid HTML, even though it may look fine in a browser, it may look different when exported to PDF or Word formats.

    Recommendation: Use something like HTML TIDY to clean up Wiki block HTML before exporting.

  • Cross-references created in Polarion will survive a Word Round-trip, but instead of scrolling in the Word document, they will open the referenced object in Polarion. Cross-references created in Word WILL NOT be recognized when imported into Polarion.

Figure 15.30. Export Document Dialog

Export Document Dialog

Document export options control the level of change available in the exported document

See also: User Reference: Macros and Wiki Mark-up Support in Word Round-trip.

Note that organizations can optionally implement restrictions via the plugin API to influence the template used for export to Microsoft Word and Excel, with restrictions on individual exports by individual users, to include a watermark in the exported documents and/or to conform to other required policies. If such a plugin is in use, the Round-trip: Export Document dialog shows a message: "The selected template may be substituted with one that complies with company policy."

TIP

Embedded image or attachment previews are preserved during the Word Round-trip process.

Exporting for Review

When you export a Document to Word using the Export for Review option, changes to the exported document are limited to comments only. No other content can be changed.

To export a Document for review/comments only:

  1. Open the document in the Document Editor. (Click on it when browsing Documents and Pages in Navigation or in search results.)

  2. In the Document Editor toolbar, click the Actions Menu button and choose Word Round-trip > Export Document. The Round-trip: Export Document dialog appears.

  3. In the Round-trip: Export Document dialog, select the Review.

  4. If you want to exclude comments currently in the Document from the export, check the Export without comments box.

  5. Click Start. When prompted, choose a location to store the exported document and click OK.

Exporting for Prioritization

When you export a Document to Word using the Export for Prioritization option, changes to the exported document are limited to selected Work Item data fields and comments. The Description field of Work Items is always read-only in the exported file.

To export a Document for prioritization or Work Item data changes only:

  1. Open the Document in the Document Editor. (Click on it when browsing Documents and Pages in Navigation or in search results.)

  2. In the Document Editor toolbar, click the Actions Menu button and choose Word Round-trip > Export Document. The Round-trip: Export Document dialog appears.

  3. In the Round-trip: Export Document dialog, select the Prioritization. A table of Work Item data fields appears in the dialog listing the fields you may allow users of the exported document to change.

  4. Check the boxes next to the names of Work Item fields you wish to allow users of the exported document to change.

  5. If you want to exclude comments currently in the Document from the export, check the Export without comments box.

  6. If you want your current selections to be the default for all subsequent exports, check Remember this configuration.

  7. Click the Start button. When prompted, choose a location to store the exported document and click OK.

Exporting for Collaboration

When you export a Document to Word using the Export for Collaboration option, changing all document content is permitted, as well as changes to specified Work Item data fields, plus the addition of comments. The Description field of Work Items is always read-write.

To export a Document permitting full collaboration and content changes:

  1. Open the Document in the Document Editor. (Click on it when browsing Documents and Pages in Navigation or in search results.)

  2. In the Document Editor toolbar, click the Actions Menu button and choose Word Round-trip > Export Document. The Round-trip: Export Document dialog appears.

  3. In the Round-trip: Export Document dialog, select the Collaboration, then click Start. A table of Work Item data fields appears in the dialog listing the fields you may allow users of the exported document to change.

  4. Check the boxes next to the names of Work Item fields you wish to allow users of the exported document to change.

  5. If you want your current selections to be the default for all subsequent exports, check Remember this configuration.

  6. Click the Start button. When prompted, choose a location to store the exported document and click OK.

Table of Contents Export

If a Document was created using the import from Word feature, and the original document contained a table of contents (TOC), the properties of the original TOC are stored during the original import, and used when the Document is exported via the Word Round-trip feature. The TOC in the resulting Word document has the same properties as the TOC of the original source document, and they cannot be changed in the exported Word document.

If the Document was created as a new Document via the portal, and if it contains a TOC, the Word Round-trip exporter creates a standard TOC in the exported Word document.

Using Round-trip Export Templates

When you create a new document via import from Word, Polarion creates a Word template file named roundtrip.docx based on the styles in the original document. If you later export the Document from Polarion using Word Round-trip Export, the content of the Document in Polarion will be formatted according to the template that was stored during the initial import.

Polarion comes with a global default export template that defines header, footer, and basic styles. The template is used to format Word documents created from Polarion Live Documents using Word Round-trip Export. You can optionally create a copy of this template for specific projects.

You can customize any export template to define the styling of the exported Round-trip document as described later in this chapter. For information on accessing round-trip export templates, see the User Reference topic: Round-trip Export Template Locations.

A Word Round-trip template can define styles for all the heading levels using paragraphs with text "Heading N" where N is the heading level number (e.g. 7). All the defined styles can be used in the round-trip Document by users to create headings. If the template does not include enough heading styles for the exported Polarion Document, the needed styles are created by Polarion with names "Heading N", where N is the level number. Note that Microsoft Word does supports only 9 heading levels, even in the numbering, so the headings above Heading 9 level cannot have an outline number.

To customize a round-trip export template:

  • Navigate to the Administration topic Work Items > Round-trip Template in the repository or project scope, or to its location in the repository using the Repository Browser.

  • Download the roundtrip.docx to your local system.

  • Edit the roundtrip.docx file in Word to defines the styles you want, saving your changes locally.

  • Upload the edited roundtrip.docx file back to the repository in the same location you took it from, using the relevant Administration page or the Repository Browser.

    If you downloaded a template file in order to create a project-scope round-trip export template for a project that did not already have one, upload to the project location described in Round-trip Export Template Locations.

Note that you will need repository read and write permissions for the templates folder. For information on field IDs that you can include in a customized template, please see User Reference topic Round-trip Export Template Fields

Document-specific Export Template

When editing any Document, the Word Round-trip Template of the Document Properties panel of the Document Sidebar enables you to upload a Word document to be used as the export template for Word Round-trip exports of the current Document. Microsoft Office Word documents saved in .docx format can be used to create a template for Word Round-trip, or you can upload a customized Word Round-trip template previously downloaded from Polarion. When you click the Upload link in the Document Properties panel of the Document Sidebar, the Upload Round-trip Template dialog presents options for each type of upload.

If a round-trip template exists:

  • The Download link is enabled in the sidebar pane which you can use to download the current round-trip template for customization. A mouse-over tool-tip indicates which template is available for downloading: default or custom.

  • The Remove (use default) link is enabled. Clicking it removes the previously uploaded Document-specific round-trip template. The default round-trip template for the project will then be used for any Word Round-trip operations.

Figure 15.31. Document Properties Panel

Document Properties Panel

The Document Properties panel of the Document Sidebar provides access to a round-trip template file used for round-trip operations with the Document. May be either the global or project default template, or a customized template uploaded by a user.

Customizing Header and Footer

You define a header and footer as you would normally do in Word. However, you can include some pre-defined "expandable" properties in the header/footer in content controls:

  • documentName (this is the Document's ID)

  • documentTitle

  • revision

  • date (date picker content control in Word)

  • generated

  • generatedBy

  • projectId

  • projectName

  • space

  • spaceTitle

  • updated

  • updatedBy

  • created

  • createdBy

  • productName

  • productVersion

(For descriptions of these, see the User Reference topic Round-trip Export Template Fields).

Polarion will fill these content controls, if present, when the Document is exported with Round-trip Export.

To add one of the above variables to a header/footer you add a plain text content control to header/footer and set its tag to the value of the identifier. (For more information see the web page: How to enable Developer ribbon and insert a content control.)

Customizing the Table of Contents

Using the Table of Contents feature in Word, insert a table of contents into the round-trip export template document if one is not already present, or if you want to change the style of an existing table. Set the depth of the table of contents in the usual way in the Word version you are using.

Customizing Styles

The default templates contain several content elements... headings, paragraphs, etc. with some default styles. Use the Format Styles feature of Word to change the properties of any existing style in the round-trip template you are customizing. Do not simply change the style of the individual element (heading or paragraph) using Format Paragraph of Format Font, etc.

Re-importing Shared Documents

After an exported round-trip document has been changed, it can be re-imported to Polarion to synchronize the changes with the original LiveDoc Document. Before re-importing, make sure the changed round-trip document is in some location that is accessible when you are working in Polarion.

To re-import a previously exported round-trip document and synchronize external changes:

  1. Open the original Document in the Document Editor. That is, the document that was previously exported using the Word Round-trip > Export Document command on the Document's Actions Menu menu. (Click on the Document name when browsing Documents and Pages in Navigation or in search results.)

  2. In the Document Editor toolbar, click the Actions Menu menu button and choose Word Round-trip > Import Changes. The Round-trip: Import Changes dialog appears.

  3. In the dialog, click Browse, navigate to and select the Word document you wish to re-import.

  4. Check any of the options you want to apply to the re-import process:

    • Overwrite Conflicts: If checked, then changes in the re-imported document that conflict with the online Document will take precedence and overwrite the same part of the Document. If this option is not selected, and conflicts occur, the import will fail and no changes will be imported to Polarion, even on-conflicting changes.

    • Import Only Comments: If checked, all changes made to the exported Word document will be ignored by the re-import process except any comments which were added. Comments will be added to the Document in the same position as the appear in the Word document. No text is replaced.

  5. If you want future round-trip re-imports to use the same options, check Remember this configuration.

  6. Click Start to launch the round-trip re-import process. Assuming there are no conflicts that are overwritten via the Overwrite Conflicts option, the Live Document in Polarion is updated.

Notes on Re-importing

When a round-trip Document is re-imported to Polarion...

  • If a user changes any Document text (i.e. text that is not part of a Work Item), or any Work Item field(s) on server after the round-trip export, and the same text and/or field data is changed externally in the round-trip document, when the round-trip document is re-imported, a conflict is reported. Import can succeed only if the Overwrite Conflicts option is chosen during the re-import operation.

  • If Document text is not changed in the round-trip document, then there is no new revision of the underlying system data file after import (but it still shows in Document history).

  • If Work Item description or any other field is unchanged in the round-trip document, there is no change in the field(s) in the history of the Work Item.