Documents

This section provides reference information on Polarion LiveDoc Documents.

Create LiveDoc Document Dialog

Access point: Index page of any space. Click the icon on the page toolbar, select New LiveDoc Document.

Table 2.6. Dialog Fields

FieldDescription

Title

Human readable title of the Document. Supports non-ASCII characters. Contained Work Items can be searched using the Document Title visual query element, entering any part of the value. A value is required.

Should not be confused with the Document heading style "Title".

Name (ID)

The unique system identifier of the Document within the project and space. Only ASCII characters may be used. Contained Work Items can be searched using the Document ID visual query element, entering the exact value only. A value is required.

Type

The Document Type. Appears only if Document Types are enabled in the system configuration. Field list contains all the Document Types currently configured in the current scope. If present, it is a required field.

Space

(or Subspace)

Name of the Space or Subspace in which the new Document will be stored. Field list contains the names of all spaces and subspaces in the current scope. Value defaults to the space name from which the dialog was invoked.

Work Item Type

Specifies which type of Work Item the new Document will contain (Addition types can be added after the Document is created.) Field list contains the names of all Work Item types currently configured in the current scope. Value defaults to the type specified as the default type in the Work Item Types configuration in Administration.

Link Role

Defines the relationship that hierarchically structured Work Items in the Document will have to each other. Field list contains the link roles currently configured in the current scope.

Enable Outline Numbering

If checked, Work Items in the new Document will automatically be outline numbered based on the Work Item level and position in the Document.

Prefix

Optional. If specified, the value is prepended to each outline number.

Document Sidebar Selector

The document sidebar selector () is available when editing a Document. It can display any of several sidebars showing comments, Document outline, and other information about the Document. There is also access to tools such as Test Run planning. Select the desired sidebar via the Sidebar drop-down menu on the Document Editor toolbar.

The next sections describe the different Sidebar panels.

Comments Sidebar

Figure 2.8. Document Sidebar Comments

Document Sidebar Comments

View, compose, and manage comments in a Document

This panel shows the comments that have been inserted into the Document, if any. It also enables adding of new comments (including threaded replies to existing comments), and removal of existing comments. Note that Document comments are not the same as the Comments field of a Work Item.

Component Descriptions:

  • Add Comment - Adds a new comment thread to the Document.

  • Reply - Appears inside a comment balloon when the balloon is selected. When clicked, adds a new threaded comment one level down.

  • Delete comment - Appears inside a comment balloon when the balloon is selected. Removes the selected comment from the Document. Comment is not actually deleted in the repository until the Document is saved.

  • Sidebar Settings - When clicked, displays a drop down menu of settings applicable to the Comments sidebar. Settings:

    • Sort by Document/Time - controls the sort order of the comments appearing in the Sidebar.

    • Show Resolved Comments - toggles visibility of comments and comment threads that have been marked as resolved. (Resolved comments and threads are hidden to keep them out of the way of subsequent comments and discussions.)

    • Show/hide Unreferenced Comments - toggles appearance of unreferenced comments in the Comments page. Unreferenced comments are comments that have been removed by deleting their icon in the Document text, but which still exist in the Document repository.

  • Close - in the sidebar's header. Closes the Comments panel.

Work Item Properties Sidebar

Figure 2.9. Document Sidebar: Work Item Properties

Document Sidebar: Work Item Properties

Manage display of Work Item data fields, edit fields, and create, view, follow, and edit links

This panel shows Work Item data fields that can be edited from the Document. It enables a user to specify which data fields appear in the panel, and in what order.

The panel also shows outgoing links from the Work Item currently selected in the Document. Users can access the linked items, create new links via pasting, and to manage links in a pop-up dialog.

Component Descriptions:

  • Label: Shows the ID and Title of the Work Item currently selected in the Document body.

  • Section "Properties" - Displays edit controls for the Work Item data fields currently enabled for editing from the Document.

  • Section "Links" - Displays type icon, ID, and Title of all Work Items to which the currently selected Work Item has outbound links. Each item is a hyperlink. If the target item is in the same Document, the link leads to the properties of the linked Work Item, which display in this pane and replace the previous information. If the link is to an item external to the Document, the item opens in s separate browser tab or window.

    Multiple links are split into categories according to link role (e.g. "has parent", "implements", etc.).

  • >Edit Links - Launches the Linked Work Items dialog which enables user to manage linking of the Work Item currently selected in the Document. See User Guide: Working with Documents: Editing Work Item Links: Using the Linked Work Items Dialog.

  • Section "Documents" - Displays the name of the Document that contains the selected Work Item, and the names of other Documents in which the selected Work Item is referenced (if any). Names of referencing Documents are clickable links that open each referencing Document.

  • Sidebar settings - displays a menu with options applicable to this sidebar. See next section.

Sidebar Settings:

The Select Fields menu option leads to the Select Fields dialog. The dialog displays a list of all standard fields for the Work Item currently selected in the Document. Custom fields may be added to the list of Available Fields using the link Add Custom Field ID. Fields in the list on the right appear in the Fields section of the panel. User can remove fields by selecting fields in the right-hand list and clicking Remove button, or add fields by selecting them in the Available Fields list and clicking Add button. Fields can be moved up or down in the list by first selecting, then clicking either the Up or Down button in the dialog. The Reset button returns the Work Item selection to the default settings.

The Set as Default button applies the changes and makes them the default for the Document. Other users will see the selected fields in the Work Item Properties sidebar. The Set as Personal button applies the changes and makes them the default for the current users. Other users see the Document default fields in the sidebar.

When a field is selected in the right-hand list, several options appear in the dialog for how to display the field.

  • Show in Sidebar Only - the field only appears in the Document sidebar

  • Show in Document Only - the field only appears in the Document

  • Show in Document and Sidebar - the field appears in both Document and Document sidebar

  • Show At - Appears only if option to show field in Document is selected. Controls whether to show the field at the start or end of Work Items.

  • Render As - Appears only for Polarion fields that have an associated icon, and only if option to show field in Document is selected. Controls whether the Work Item in the Document displays as icon, text, or both.

  • Show Fields at End as Table - If checked, any fields having option set to show them at the end of Work Items will be formatted as a table.

Recycle Bin Sidebar

Figure 2.10. Document Sidebar: Document Recycle Bin

Document Sidebar: Document Recycle Bin

View Work Items in repository that are no longer used in the Document. Access options for handling them.

This panel displays Work Items removed from the Document but still stored in the repository, and provides tools for handling them. It can be accessed from the Document Editor toolbar, and via a button Open in Document's Recycle Bin on toolbar of Work Items currently in the Recycle Bin, when such items are viewed in the Table view of the Work Items Tracker. Options are:

  • Insert Work Item(s) into the Document

  • Delete Work Item(s) from the repository.

  • Move Work Item(s) to another Document in the project

Component Descriptions:

  • Check box: unlabeled - Selects all Work Items in the Recycle Bin.

  • Insert - inserts selected Work Item(s) into the current Document at the current insertion point, and re-associates the item(s) with the Document.

  • - permanently deletes selected Work Item(s) from the Recycle Bin and the underlying repository.

  • Move - invokes the Move Work Item(s) dialog which provides the following options:

    • Move selected Work Item(s) out of Document: Disassociates the selected orphaned item(s) from the Document, but retains them as project artifacts in the repository where they are managed in the integrated Tracker and accessed via the Work Items topic.

    • Move selected Work Item(s) to Document: Associates the selected orphaned item(s) with another Document, to which they are appended. User must identify the target Document by selecting the name of the space in which the target Document resides, and then selecting the name of the target Document.

  • - refreshes the list of Work Items in the Recycle Bin. This can be useful if one user is reading the Document while another user is editing it, or if one author has removed or merged Work Items in the document since the Recycle Bin was displayed in the Sidebar.

Content Handling

The following tables provide a reference to how various actions affect moving of Work Items to the Recycle Bin.

Table 2.8. Keyboard/Context Menu Actions

ActionContent to Bin?

Mark text as Work Item and press Delete/Backspace

YES

Mark Work Item as part of selection and delete it

YES

Mark text as Work Item and CUT the entire Work Item

YES

Mark text as Work Item, CUT the entire Work Item, then PASTE it back

NO

Merge Work Item

YES

Table 2.9. Work Item Icon Menu Actions

ActionContent to Bin?

Cut

YES

Cut, followed by Paste

NO

Unmark

YES

Delete

NO

Table 2.10. Document Editor Toolbar Action

ActionContent to Bin?

Unmark Work Item

YES

Document Properties Sidebar

Figure 2.11. Document Sidebar: Document Properties

Document Sidebar: Document Properties

View properties and settings for the current Document

This panel displays several properties and settings related to the current Document:

  • Links enabling you to rename the current Document, or change its type.

    Document types must be enabled in the project configuration or the Change link is disabled.

  • Document custom fields and Document workflow status, if these have been configured for the project. (See Administrator's Guide: Configuring Document Custom Fields and Configuring Document Types and Workflow).

  • Controls to turn Auto-suspect (for Work Items) on and off.

  • Controls to turn outline numbering on and off, and to specify a prefix for outline numbers.

  • Button to toggle on-demand loading of Work Items in the Document. On-demand loading can significantly improve usability of Documents containing a large number of Work Items. When enabled, only a few Work Items are initially loaded, enabling the Document to be viewed right away. Other items are loaded as the user scrolls. There are currently some limitations.

  • Links to the Microsoft Office Word template used for Word Round-trip export.

  • Edit Links: Adds Remote Linked Data or edits existing links to the LiveDoc.

If the Document is a branched Document, the panel shows the name of the master Document and provides a link to it.

Document Outline Sidebar

Figure 2.12. Document Sidebar: Document Outline

Document Sidebar: Document Outline

View the outline structure of the current Document and jump to content

This panel displays the outline structure of the current Document.

  • The tree contains nodes for headings and Work Items contained in the Document.

  • Clicking any node in the tree structure scrolls the Document to show the selected content. Selecting content in the Document selects the equivalent node in the outline.

  • When content is added to or removed from the Document, the Update button in the page may be used to refresh the outline.

  • The panel provides a filter for the outline, which can help locate content quickly in a large Document. Simply type filter text in the edit control to automatically and incrementally search the outline structure. Clear the edit control to remove filtering and restore the full outline.

Attachments Sidebar

Figure 2.13. Document Sidebar: Attachments

Document Sidebar: Attachments

View and manage a Document's file attachments in the Attachments sidebar.

This sidebar enables you to add new attachments to a Document, insert an image or attachment preview and to view and manage the list of existing attachments.

Component Descriptions:

  • Sidebar header - The icon displays a menu with the following items:

    • Sort Alphabetically - The default setting. Sorts the list of attachments alphabetically by file name.

    • Sort by Time - Sorts attachments from newest to oldest.

    • Hide Attachments Visible in Document - Hides the panel section Attachments Visible in Document and any attachments listed under it. This is useful if the there are many image or attachment previews visible in the Document body and you only want to focus on other attachments in the Attachments sidebar.

  • Search box - Filters the list of attachments according to the sting entered: "abc" matches "abc", "abcd" or "xabc", etc.

  • - Refreshes the list of attachments. (For example, another user might add an attachment while you are viewing the Document.)

  • Upload New Attachment - Lets users select a local file and upload it as an attachment to the Document. (The document must then be saved to complete the attachment process.)

  • Insert Preview: Inserts a Preview of the image or attachment into the document where the cursor is placed.

  • Download: Downloads the object to the browser's download folder.

  • Update: Upload an updated version of the previewed object. (Is disabled for read-only documents or for users with read-only permissions.)

  • Delete: Deletes the selected attachment.

  • Label - Attachments labels the section of the sidebar that lists all attachments that are NOT displayed in the Document's body. It may contain images, Visio diagrams and other types of files. Files listed in this section can be inserted into the Document body byplacing the cursor at the desired spot within the document and clicking Insert Preview button . Once inserted there, they are removed from this listing in the Attachments panel and added to the Attachments Visible in Document section.

  • Label - Attachments Visible in Document labels the section of the panel that lists all the attachments currently displayed in the Document body. This section may be hidden using the Hide Attachments Visible in Document item in the (Pane Settings) menu. When hidden, it can be restored using the Show All item in the same menu.

Pasting Images

CTRL +V or Command +V can be used for images within the document, but if they are used for an image in a Work Item within the document, its thumbnail will NOT appear in the Attachments sidebar.

Tips:

  • No changes to a Document's attachments are permitted if the Document is derived from another Document. The original Document's attachments must be changed or updated.

  • Clicking on an attachment representing an image displayed in the Document body scrolls the Document to its first appearance.

  • Deleting an attachment representing an image displayed in the Document removes the image from all places where it was displayed in the Document.

Test Run Planning Sidebar

Figure 2.14. Document Sidebar: Test Run Planning

Document Sidebar: Test Run Planning

Populate a Test Run with Test Cases from the current Document

This panel enables you to select Test Cases to be executed when a Test Run is executed by testers. For information see User Guide: Creating and Managing Test Runs: Selecting (Planning) Test Cases.

Component Descriptions:

  • Label - ID {name} shows the ID of the Test Run for which Test Cases are being selected or removed.

  • Label - Template {name} shows the name of the template on which the Test Run shown in ID is based.

  • Panels - Waiting shows a count of the Test Cases currently populating the Test Run. Executed shows a count of the Test Cases current populating the Test Run which have not currently been executed.

  • Add - adds one or more Test Cases, selected in the Document body, to the queue of waiting Test Cases for the Test Run. Enabled when Test Case(s) not already in the Waiting queue is/are selected in the Document.

  • Remove - removes one or more selected Test Cases, selected in the Document body, from the queue of waiting Test Cases for the Test Run. Enabled when Test Case(s) already in the Waiting queue is/are selected in the Document.

  • Panel - Estimated Execution Time displays the total estimated time needed to execute all Test Cases currently populating the Test Run. Each Test Case has a field for storing the estimated time needed to execute it.

  • Save Test Run - saves the current Test Case selection to the Test Run.

Configure Work Item Presentation Dialog

Invoked from the Document Editor toolbar of an open Live Document (accessed from Navigation: Documents and Pages).

Content elements in Documents can be marked as Work Items - a paragraph can be marked as a Requirement, for example. Marking of elements may be done automatically via Work Item Rules when a Document is created via import from Word, or explicitly by a user working on the Document. The Configure Work Item Presentation dialog is where you can specify which type(s) of Work Items the Document can contain, and customize the presentation of elements marked as Work Items so that they display certain Work Item data field values in addition to the textual content. For example, you might display the Work Item ID and severity in paragraphs marked as Requirements, or the ID and status in paragraphs marked as Test Cases.

You can display the value of both standard Work Item fields and Custom Fields via the Select Fields button. You can specify whether field values appear at the start of the Work Item, or at the end. For example, you might display the value of the outlineNumber field at the start, and the severity field at the end of paragraphs that are marked Work Items. You can display multiple field values at both the beginning and end of marked elements. For example, you might show outlineNumber and id at the start, and severity and timePoint at the end of paragraphs marked as Work Items.

Figure 2.15. Configure Work Item Presentation Dialog

Configure Work Item Presentation Dialog

Adds support for multiple Work Item types in a Document and specifies fields to appear along with text

Each row in the table represents a Work Item type. Document content can be marked as a Work Item of any type specified in this dialog.

Fields:

  • Type: Specifies a Work Item type to be supported by the Document. The list contains the types currently configured for the project in the workitem_type_enum.xml enumeration (see Administrator's Guide: Configuring Enumerations.

  • Label: The name of the Work Item type specified in Type. This value appears in the drop-down menu of the Document editor toolbar. Value defaults to the configured name of the Work Item type selected in Type. User can change it, but there is usually no need to do so.

  • Content: Specifies what Work Item content will be included when a new Work Item is inserted, or Document text is manually marked as a Work Item of the type specified in Type. Take note of the following:

    • If you select Description, all selected content is placed in the Work Item's Description and no value is set for its Title. When viewed in the integrated tracker, the Work Item's Title field will be derived from the first 80 characters of the Description. No separate title appears in the Document.

    • If you select Title and Description, all selected content is placed in the Description, and a line for Title is created which the user fills in. Title is maintained as a separate data field from Description.

    • If the setting in Content includes Title and/or Description, the ENTER keyboard shortcut has different behavior in these fields.

  • No Page Break: When checked, then Polarion will attempt, so far as possible, not to have page breaks within Work Items when exporting the Document to PDF, or round-trip for Microsoft Word.

  • Hidden: If checked, the Work Item type is not displayed in the drop-down menu of the Document Editor toolbar. The presentation will be applied to existing Work Items of the type specified in Type (if any), but users will not be able to apply it manually to new or existing Document content.

  • Actions: The icon adds another row to the table in which support for an additional Work Item type can be configured for the Document. The icon removes a row from the table, removing support in the Document for the specified Work Item type. The remove icon is disabled, and the row for the Work Item type cannot be removed if any Document content has been marked as a Work Item of the type defined by the row. The content must either be deleted from the Document, or unmarked as a Work Item in order to remove a row from the table, and support for the Work Item type it represents.

    The Select Fields button leads to the Select Fields dialog in which you can specify which Work Item fields should appear in the Document, and where they should appear. You can opt to show any field (including custom fields) in the Document, the Document Sidebar (Work Item Properties page) or both. Some fields (usually of Enumeration type) allow you to specify whether they appear as text, as an icon, or both. (Note that this dialog can also be opened via Select Fields menu item of Work Item Properties page of the Document Sidebar.)

    Fields configured as showing in the Document will be exported to PDF, and to Microsoft Word for Word round-trip.

    TIP

    The Select Fields dialog can also be invoked via the (Pane Settings) icon in the Work Item Properties sidebar (enabled when a Work Item is selected in a Document). When invoked from there, the fields configuration can be saved as a user-specific personal configuration only for the current user, or as the default for the Document.

Outline Numbering Display

When outline numbering is enabled in Documents, outline numbers appear for Document headings and Work Item titles in the Document Editor (see User Guide topic Work Items in Documents: Using Outline Numbering). This topic describes the display of outline numbers in the Table and Tree Table views of Documents, including Work Items referenced from a different Document.

  • If an outline number is assigned to a Document-based Work Item, then the Work Item Table and Tree Table views show the outline number from the master Document ( the Document that actually contains the original item).

  • When a Document is selected in Navigation and viewed in the Table or Tree views, and a Work Item is selected the table or tree, the outline number you see in the Outline Number column of the table/tree is the outline number from the Document selected in Navigation. The value in the Outline Number field in the selected Work Item's detail form may be different from the value in the table column if the item is referenced from another Document. In that case, the value in the field is the outline number of the item in the Master Document - the Document that actually contains the Work Item and from which it is referenced to other Documents.

  • If a Work Item has no outline number assigned, then the Outline Number column in the table section of the page shows only icon representing the Work Item type.

Figure 2.16. Outline Numbers in the User Interface

Outline Numbers in the User Interface

Outline numbering display for referenced Work Item in Tree Table view of Document

PDF Watermarks Order of Precedence

The order of precedence used by the PDF exporter for watermark images in PDF output is as follows:

  1. Exact match (confidential_portrait_A4.png)

  2. Default for orientation (confidential_portrait.png)

  3. Bigger size for the same orientation (confidential_portrait_A3.png)

  4. Smaller size for the same orientation (confidential_portrait_letter.png)

  5. Default (confidential.png)

  6. The same size for the other orientation

  7. Default for the other orientation (confidential_landscape.png)

  8. Bigger size for the other orientation (confidential_landscape_A3.png)

  9. Smaller size for the other orientation (confidential_landscape_letter.png)

Project repository is checked first, followed by global repository. If no suitable image is found in any scope, no watermark is included in the PDF output, and an error is written to the log files. For additional information, see Configuring Export Watermarks > Multiple Watermark Images.

Permissions and License

Your ability to access and use Document features depends on the permissions assigned to your user account, which may be tied to the user role(s) assigned to you by the system or project administrator. The license you are currently using may also affect your ability to use some Document-related features. This section provides some specifics that may help if you find you cannot access or use some feature or perform some operation.

Word Import and Round-trip

Word Import

  • The Import action is only available if you have permission to create Documents and Work Items and you are using either a Polarion ALM or Polarion Requirements License.

  • Even if you have user permissions as above, you can only save import rules if you have write permission for the relevant repository location, i.e. .polarion/tracker/import_configurations/word/.

Word Round-trip

  • You can invoke Word Round-trip > Export when you have read-only permission for a Document provided you are using a Polarion Requirements or Polarion ALM license.

  • To import changes in a modified exported Word document, you need to be using a Polarion Requirements or Polarion ALM license, and you need to have write permission for the Subversion repository, and also Polarion permission to modify the Document.

Document Features and Operations

Polarion provides project managers the ability to exert control over who can do what with a Document. This is accomplished by configuring Document permissions in global and/or project administration. This section describes the Document permissions that can be assigned and what they allow users who have the respective permissions.

Note

The MODIFY permission for Documents implemented in Polarion versions prior to version 2014 SR2 is replaced by the MANAGE, MODIFY FIELDS, MODIFY CONTENT permissions. If MODIFY was granted, the 3 new permissions will be granted after updating. Likewise, if MODIFY was denied, the new permissions will also be denied. The net outcome is that users should not experience any difference in what they are able to do with Documents.

See also: Administration Reference: Dynamic Roles and Permissions: Dynamic Roles for Documents.

Document Access and Content
READ

Allows user to read Document content and view Document information is Document sidebar panels.

CREATE NEW

Allows user to create new Documents, provided that user is also granted MANAGE, MODIFY FIELDS, and MODIFY CONTENT permissions.

MODIFY FIELDS

Allows user to modify Document fields (Status, for example) and custom fields shown in the Document Properties sidebar panel.

Granting of the MANAGE and/or MODIFY CONTENT permission for Documents does not grant the permission to MODIFY FIELDS.

MODIFY CONTENT

Allows user to modify Document content. Specifically:

  • Add/remove/move Work Items, including Headings and referenced Work Items, to/from/within the Document structure using the Document Editor.

  • Move Work Items, including Headings and referenced Work Items, to/from the Document Structure via the Move Work Item dialog.

  • Fields that appear in the Content column of the Configure Work Item Presentation dialog (i.e. Title, Description, and Test Steps).

  • Add, modify, or remove Document attachments.

  • Add, modify, or remove attachments to Work Items of all types contained in the Document (including Headings), provided user also has permission to modify Work Items in the project.

  • Add, edit, or delete plain text in the Document. That is, text which is not contained in Work Items.

Additional notes on this permission:

  • Users who are denied this permission, but who are granted the COMMENT and/or RESOLVE COMMENT permission, can insert comments into the Document and/or resolve comments in the Document (in text and Work Items).

    IMPORTANT: If MODIFY CONTENT is granted, do not also explicitly grant COMMENT or RESOLVE COMMENT permissions. The granted user will automatically be granted them.

  • This permission does not apply to referenced Work Items in the Document.

  • Granting this of permission does not grant permission to MODIFY FIELDS.

  • Granting of the MANAGE permission for Documents does not grant permission to MODIFY CONTENT.

MANAGE

Allows user to:

  • Configure default Work Item type(s) and Work Item presentation for the Document.

  • Change the Document type (if the Document types feature is enabled).

  • Rename or move the Document.

  • Upload a round-trip template.

  • Configure Document outline numbering.

  • Enable/disable Auto-suspect for Document Work Items.

  • Delete comments from a Document.

User must also have the MODIFY and MODIFY-FIELDS permissions for Documents.

DELETE

Allows the user to delete Documents.

Document Comments
COMMENT

Allows:

  • Create new Document comments

  • Reply to Document comments

RESOLVE COMMENTS

Allows user to resolve Document comments.

Permissions for Document Actions

The following table lists the permissions required for different Document-related actions, and the capabilities/features available when a user has the listed permissions.

Action: View Document objects in user interface

Required Permissions:

  • READ Document

  • READ Work Item

Notes:

  • Documents appear in Navigation Documents and Pages topic.

  • Documents are listed in space Index pages and overviews.

  • Documents can be opened (e.g. from links).

Action: Read a Document

Required Permissions:

  • READ Document

  • READ Work Item

Notes:

  • Documents are read-only.

  • Round-trip and PDF exports will work.

Action: Create a new Document

Required Permissions:

  • READ Document

  • MODIFY Document

  • CREATE Document

  • READ Work Item

  • MODIFY Work Item

  • CREATE Work Item

Notes:

  • Option to create new Document appears in space Index pages and space Overview.

  • Import for Microsoft Word is available.

Action: Modify a Document

Required Permissions:

  • READ Document

  • MODIFY Document

  • CREATE Work Item

  • READ Work Item

  • MODIFY Work Item

Notes:

  • Modify Document body text.

  • Modify Work Item description and fields.

  • Mark/paste OR unmark/cut/or recycle bin Work Items.

  • Mark/paste OR unmark/cut/delete Headings.

    If you want to control the deletion of headings via the "DELETE" permission, then set the headingsObeyDeletePermission property to true.

    (Otherwise it's enough to have the "MODIFY CONTENT" permission.)

  • Round-trip import is available.

Action: Delete a Document

Required Permissions: Same as for Modify a Document, plus DELETE Document

Notes:

  • Option to delete Documents appears on space index pages.

Action: Re-import changes in exported round-trip (Word) document

Required Permissions: Same as those for Modify a Document

Notes:

  • Changes are imported if there are no errors or invalid data.

Macros and Wiki Mark-up Support in Word Round-trip

This section the level of support in the export operation of Word Round-trip for text formatted with Wiki mark-up and inserted into a Document, and for Wiki macros which may be inserted into a Documents. Items with full and partial support are listed. You can assume that any mark-up and macro not listed here is not supported when a Document is exported to Microsoft Office Word using the Word Round-trip feature. It may still be possible to export Documents containing unsupported mark-up and/or macros, but formatting and content in the exported document may be sub-optimal or missing.

The following macros and other elements are supported:

  • Headings: converted to Word as native Word headings; style of Wiki/Document headings is not preserved

  • Generic formatting, including: bold, underlined, italic, strike-through, monospace, subscript and superscript

  • URL links (e.g. [https://www.polarion.com], [Polarion >https://www.polarion.com]

  • Lists (unordered, ordered, hybrid multi-level)

  • Escaped text, explicit line break (i.e. '\'), horizontal rule (i.e. '---')

  • {code} macro: text is converted into Word in monospace font (Courier New)

  • {quote} macro

  • {workitems} macro (Note: some styles may not be converted, but the macro is generally supported)

  • Document macros:

    1. {document}: link is converted to Word (with icon)

    2. {document-workitems}: Note that tables are not converted completely to Word.

    3. {document-property}

  • Project macros:

    • {project-property:active}

    • {project-property:description}

    • {project-property:finish}

    • {project-property:lead}

    • {project-property:location}

    • {project-property:name}

    • {project-property:[PROJECT NAME]|users}

      Where [PROJECT NAME] is the name of a project. Example: {project-property:drivepilot|users}

    • {project-property:start}

    • {project-property:users}

  • {pages} macro

  • {timepoint} macro

  • {show:pdf} macro: the content is shown only when document is exported to Word

Partially Supported Items

The following elements and macros are partially supported during export to Word. For example, content may export but formatting does not.

  • Links: [Project/Space.Page], {portallink:/monitor}Monitor{portallink}

  • {table} macro

  • Boxes: #message(), #info(), #warning(), #error()

  • User macros: {user}, {users}

  • Dashboard macros: {dashboard-property}, {report}

  • Factbase: e.g. {fact:base=repo-analysis|value=NOF}

Import Rules for Tables

When importing a Word document in which content that should be recognized as Work Items is contained in a table, you need to specify an import rule that will recognize Work Items in tables. You may also want the rule to execute some action(s) on these table-contained Work Items when the Word document is imported to Polarion. This is done using regular expressions with the text matching regex rule type option. This topic provides some examples.

Suppose you have the following table:

Table 2.11. Example of a table in a Word Document to be imported

Risk

High

Steps


                                        Hello
                                        World
                                        

Department

34

These regular expressions can be used to parse the values from the above table:

The selected fields must actually exist within the target document in order to work.

  • Single line: Risk[\s&&[^\t]]*\t([^\t]*)\t\n

  • Multiple lines: Steps[\s&&[^\t]]*\t([^\t]*)\t\n?

Figure 2.17. Import Rule to Parse a Table for Values

Import Rule to Parse a Table for Values

"text matching regex" rules specified in the Document import preview

See also: User Guide: Working with Documents: Configuring Automatic Work Item Recognition.

Managing Saved Import Configurations

If users have created and saved Document import configurations (i.e. rules for recognizing Work Items in imported Word documents), at some point in may become desirable to delete some configurations that are no longer necessary or used. There are several points to remember about deleting import configurations:

  • There is no graphical user interface for deleting import configurations. They must be deleted from the repository.

  • The repository folder storing import configurations is:

    /.polarion/tracker/import_configurations/word or [PROJECT]/.polarion/tracker/import_configurations/word

    You can use Polarion's Repository Browser or an external Subversion client to browse to the import configuration folders.

  • If an import configuration for the repository scope has been overridden in a project, the configuration cannot be deleted at the repository level.

  • A user must have change permissions for the repository folder(s) containing import configurations in order to delete any import configuration.

See also: User Guide: Saving Work Item Rules for Reuse.

Import and Export Formatting

Polarion always attempts to preserve the formatting of imported Microsoft Word and Excel documents, and of exported Polarion LiveDocs. In general:

  • Font size and family is imported from Word and Excel documents except the Normal style.

  • Polarion imports only known fonts defined by the system configuration that are replaced on import by the font substitution settings of the Polarion system.

  • Text color and text and table cell background color is imported from Word and Excel documents. Text background color set text strings in body text or table cells is not imported. In cells, only the cell background color is imported.

  • Font size, font family and colors are exported during Word and Excel round-trip.

  • Font size, font family and colors are exported by PDF Export

Round-trip Export Template Fields

The following IDs can be set in a project-scope Word Round-trip export template, and are visible in the header or footer of exported round-trip files:

Table 2.12. 

IDDescription

created

Date/time when the Document was originally created

createdBy

User who originally created the source Document

date

Current date

documentName

System ID of the source Document

documentTitle

Title of the source Document

generated

Date the round-trip document was created

generatedBy

Name of the user who exported (generated) the round-trip document

productName

Name of the Polarion product used to create the round-trip document

productVersion

Version identifier of the Polarion product used to create the round-trip document

projectId

ID of the project containing the source Document in Polarion

projectName

Name of the project containing the source Document

revision

Revision number of the source Document

space

System ID of the space containing the source Document

spaceTitle

Title of the space containing the source Document

updated

Date/time when the source Document was last updated

updatedBy

Name of user who last updated the source Document

Round-trip Export Template Locations

A Round-trip Export template is a Word .docx document that is used by Polarion as a basis for creating a Word round-trip document from a Polarion Live Document. Templates can define e.g. header and footer, table of contents, heading styles, etc. This section specifies where such templates are stored in the repository in case you wish to customize them.

  • The location of the global default template, used for export of Documents created in the portal is: /.polarion/tracker/templates/roundtrip.docx. This template is accessible via the Administration topic Work Items > Round-trip Template in the Repository scope.

  • You may create and upload a project-specific copy of the global default template to be used for all round-trip exports from a specific project. Project-specific templates are stored as: [PROJECT]/.polarion/tracker/templates/roundtrip.docx. You can create and access a project-scope round-trip template via the Work Items > Round-trip Template in the project scope.

  • If a Document is created by importing a Word Document, a document-specific round-trip export template file is created and stored in the Document folder: [DOCUMENT_NAME]/templates/roundtrip.docx. This template is accessible in the Document Properties panel of the Document Sidebar. You can either upload a customized template (one that was downloaded before and modified), or it can be one you have created as a template out of any Polarion-created Document (these options are presented in the upload dialog).

For more information on using Word Round-trip and round-trip export templates, see User Guide topics: Sharing Documents Using Word Round-trip and Using Round-trip Export Templates.

Deleting Round-trip Templates

If you have default round-trip templates in some project(s) that you no longer need, these can be deleted using the Repository Browser. Navigate to the project location as described above and delete the roundtrip.docx file.

DO NOT DELETE the global default round-trip template: /.polarion/tracker/templates/roundtrip.docx

You can delete a Document-specific round-trip template using the Remove (use default) link in the Document Properties panel of the Document Sidebar in the Document Editor.

Document Editor Toolbar

This topic documents the actions available on the Document Editor toolbar. The toolbar is also available in the Test Execution View. Please refer to the following figure. Toolbar actions are listed in this topic as they appear left to right on the toolbar.

Table 2.13. Document Editor Toolbar Actions

ActionDescription

Save

Saves changes to the Document. Disabled when there are no unsaved changes.

Operations

Drops down a menu of available Document operations. See: Operations Menu.

Undo

Rolls back changes until the undo limit is reached.

Redo

Reapplies changes undone by Undo until the limit of undone actions is reached.

Paragraph Type

Applies paragraph or heading styles to the current paragraph. The maximum number of available heading levels can be configured by an Administrator. See the com.polarion.tracker.defaultNumberOfHeadings property in the Advanced System Tuning section for details.

Bold

Formats selected text, or text forward from insertion point, in bold font.

Italic

Formats selected text, or text forward from insertion point, in Italic font.

Formatting

Contains the following formatting options:

- Underline,

- Strike-through,

- Underline,

- Subscript,

- Superscript,

- Text Color,

- Text Background Color,

Font

Enables selection of font

Font Size

Enables selection of font size

Remove Formatting

Removes formatting from selected text.

Convert to Text

Converts selected items to Plain Text.

Mark/Unmark Work Item

Clicking icon marks or unmarks selected text as a Work Item. Drop-down menu enables marking selected text as one of the listed Work Item types, if multiple types are configured in the Document Work Item presentation. The Configure item access the Configure Work Item Presentation dialog where type(s) and other properties of Document Work Items are specified.

Enabled if current selection does not contain a Heading, Wiki content, TOC, or Work Item. Also means that selection does not contain two or more Work Items, or combination of more top level elements.

Enabled if current selection contains only one Work Item and nothing else.

Ordered List

Formats the current paragraph as a Numbered list (ordered list) item.

Unordered List

Formats the current paragraph as an unordered (bullet) list item.

Continue Numbering

Renumber

Presents a toggle control enabling/disabling the continuation of a numbered list that is interrupted by text not part of a list item.

  • Only top-level list items are affected. Numbering of further levels always begins with "1".

  • Continue Numbering is available for plain text, contained Work Items, and referenced Work Items.

  • Continue Numbering is available only in the Document Editor. Work Items containing continued lists will show lists continuing with "1" in other Views (e.g. Table), but the continuation is preserved in the Document.

  • List continuation is preserved in Round-trip export for Word. Changes from Word should be re-imported correctly unless a list is interwoven with a different list type - bullet list, for example.

  • Continuation is preserved in copy/paste operations within the same Document.

Outdent

Outdents the current paragraph one level. Disabled if the current paragraph is already as far left as it can go.

Indent

Indents the current paragraph one level until the indent maximum is reached.

Alignment

Sets the alignment for the current paragraph.The action will be denied if the cursor is located in a heading or Work Item text. In a Work Item description, only the alignment of images and tables is supported. (An entire table or just text in a single cell). An image is aligned only when selected.

Left aligns the current paragraph.

Center the current paragraph.

Right aligns the current paragraph.

Add Comment

Inserts a comment marker at the current cursor position, opens the Comment pane of the Document sidebar (and the sidebar itself if closed), and inserts a new comment in the Comment pane that's ready for editing.

Enabled if the current selection does not contain a Heading, Wiki content, TOC, or Work Item title.

Insert Image

Launches the Insert Image dialog with options to upload a local image, select an image attachment, or insert an image currently on your clipboard. The image is inserted at the current cursor position.

Enabled if current selection does not contain a Heading, Wiki content, TOC, or Work Item title.

Insert Menu

Insert several types of content into the Document. See: Insert Menu.

Table

Inserts a table on the current line if it is empty, or on a new line if not. It is also used to modify an existing table. (Add, Remove, Merge or Unmerge previously merged cells.)

Show Sidebar

Displays a menu of Document Sidebar panels and opens a selected panel.

View History

Displays the Document's revisions history and revision comparison features.

Home

Returns the insertion point to the top of the Document.

View

Displays a menu of Work Item Views and opens a selected View in the Work Item Tracker. The opened View contains all Work Items in the Document.

Refresh

Reloads the current Document.

Document Options

Presents a context-sensitive menu of options. The option to display Help is always present.

Insert Menu

Table 2.14. Document Editor Toolbar Insert Menu

ItemDescription

Comment

Inserts a comment marker at the current cursor position, opens the Comment sidebar, and inserts a new comment that's ready for editing.

Enabled if the current selection does not contain a Heading, Wiki content, TOC, or Work Item title.

Image or Attachment Preview

Available on the toolbars found on Pages, LiveDocs and Rich text Work Item fields. It launches the Insert Image or Attachment Preview dialog.

The dialog initially displays previews of images and attachments that are already attached.

It's also where new images or attachments with previews can be added.

Link or Cross-reference

Launches the Insert Link dialog where a Live Link URL or a Cross-reference can be specified. A hyperlink to the specified URL is inserted at the cursor position. If a Cross-reference refers to an item that contains outline numbers, you'll also have the option to include the outline numbers in the link's text. The cross-reference's outline numbers and title update automatically whenever its source's numbers or title change. (Enabled if the current selection does not contain a Heading, Wiki content, TOC, or Work Item title.)

Diagram

Launches the Diagram Editor and inserts a new diagram at the insertion point when diagram is saved in the Editor.

Table of Contents

Inserts a table of contents on the current line (if empty) or above it if not.

Enabled if current selection does not contain a Heading, Wiki content, TOC, or Work Item, and if there is no TOC already inserted in the Document. Only one TOC may be inserted in a Document.

Table of Figures

Enables insertion of a table of figures, table of tables, or a table of other items with user-defined caption labels, on the current line, if empty, or above it if not.

The type of table inserted depends on selection in the Caption Label field of the Insert Table of Figures dialog.

Wiki Content

Launches the Insert of Modify Wiki Content dialog in for selecting Wiki syntax and mark-up that inserts Wiki content (macros, for example) into the Document.

Enabled if current selection does not contain a Heading, Wiki content, TOC, or Work Item.

Page Break

Inserts a page break on a new line. Page breaks are applied when the Document is exported.

Operations Menu

Table 2.15. Document Editor Toolbar Operations Menu

ItemDescription

Filter

Displays the filter bar where you can enter a query that filters the Work Items shown in the Document. For example, the query status:open would filter the Document to show only Work Items with an "Open" status.

Find

Displays the Find dialog, enabling you to find text in the current Document. (Including text contained in Work Items.)

Find and Replace

Displays the Find and Replace dialog, enabling you to find and optionally replace text in the current Document. (Including text contained in Work Items.)

Print

Launches the Print dialog that displays a print preview of the Document and provides print options.

Export to PDF

Launches the Export to PDF dialog with several export options and exports the Document content to a PDF file.

Rename

Launches the Move or Rename dialog with options to Rename the document or Move it to another Space.

Reuse

Launches the Reuse Document dialog with options to reuse the current Document. For more information, see User Guide: Reusing a Document.

Branch

Launches the Branch Document dialog for branching the current Document to create a variant. For more information, see User Guide: Branching Documents.

Compare With

Enables user to compare the current state of a Document with some other Document, or the last saved version of the current Document.

Word Round-trip

Via its sub-menu, let you Export the current document to Microsoft Word for review, comment, or editing by an external user, and Import Changes in a previously exported Word round-trip document back into Polarion.

For more information, see Sharing Documents Using Word Round-trip.

ReqIF Round-trip

Lets you Export a document in the ReqIF (Requirements Interchange) format or Import Changes made to a ReqIF document outside Polarion, back into the portal.

Work Item Actions Menu

When Document text is marked as a Work Item, an icon representing the Work Item type appears in the left margin. Clicking the icon displays a menu with the following actions.

Table 2.16. Actions Menu Items

Open Item - Opens the Document-defined Work Item in the Table view of the tracker.

Copy ID - Copies the ID of the Work Item to your computer's clipboard.

Copy Link - Copies the complete URL of the Work Item to your computer's clipboard.

Unmark - Unmarks the current Work Item, reverting the content to regular Document text and sending the Work Item to the Document Recycle Bin (viewable in the Document Sidebar).

Delete - Deletes the current Work Item.

Insert - Inserts a paragraph above or below the current caret position via one of the sub-menu items.

Document Structure Change Via Excel

The following items apply when Document Work Items are exported to Excel using the Allow Document structure changes in Excel, and an external user modifies the Document structure in the exported Excel workbook.

  • When a heading is removed in the exported workbook, lower level headings below the deleted heading are not promoted, but rather retain the same level they had upon export from Polarion. The user should change promote lower-level headings occurring after deleting a higher-level heading.

  • An heading added in the exported workbook is always 1 level higher in the structure as compared to the previous heading.

  • If it is desired to preserve non-sequential headings occurring in a Document... "Heading 1" followed by "Heading 3", for example... then modifying headings in an exported Excel workbook is not recommended. On import, Polarion will "fix" the structure, promoting the "Heading 3" in the example to "Heading 2".

  • Related to the previous, any invalid hierarchy created in the exported workbook (missing heading level between Work Items) will be silently fixed when the modified workbook is re-imported to Polarion and the online source Document will reflect a valid hierarchy.

  • When adding a row in the exported Workbook, the user must write some content before attempting to indent it.

  • The following points apply when conflicts are encountered upon re-import of a modified exported Excel workbook:

    • If a Work Item is unmarked or deleted on server after being included in an export to Excel, and the item is not modified in the exported workbook, the importer ignores the item in the worksheet and does not re-import it. ("Modified" means modified value, not level or position.)

    • If a Work Item is unmarked on the server after being exported to Excel, and it is modified in the exported workbook, then item is updated during re-import to Polarion.

    • If a Work Item is deleted on server after export to Excel, and then modified in exported workbook, the importer treats it as a conflict. The import fails, or changes to the deleted items are ignored, depending on the import option settings selected by the user importing the workbook.

Merging of Concurrent Changes

This section outlines what actions are taken by Polarion to merge changes to Documents when users concurrently edit the same Document content.

Automatic Merging

The following concurrent Document editing actions are automatically merged without any message to users:

  • Adding elements to different places

  • Deleting elements on different places

  • Changing of different elements

  • Work Item indentation (treated as remove/add)

  • Commenting of a paragraph or Work Item description by one user that was modified by another user since the last saved revision.

  • Changing of a Work Item property after another user has reordered some other parts of the Document.

Automatic Safe Merge with Warning

The following concurrent Document editing actions are automatically merged with relative safety after a warning message to users:

  • Change to different properties of the same Work Item. Warning appears to the latest user to invoke Save. Merge is performed if user confirms Save in the warning dialog.

  • Merging of other changes if the same property(ies) of a Work Item are changed. Changes of latest user invoking Save overwrite the conflicting change in Work Item property and merges other changes if user confirms Save in the warning dialog.

Automatic Unsafe Merge with Warning

The merge algorithm tries to merge the changes made by the current user, but some of those changes may be lost or may not make sense after the changes made by another user meanwhile. The following actions will display a warning to the User that he/she should review all recent changes (in the Document history) and manually make corrections if necessary.

  • Addition or removal of a Work Item after another user reordered some parts of the Document.

  • Addition of elements (paragraphs, Work Item, etc.) to the same place in the Document.

  • Removing elements that were modified or removed concurrently.

  • Changing of the same Document element.

Merge Actions for Compared Documents

This topic outlines the various merge actions available in the Merge sidebar of the Work Items page when two Documents are compared (Document Editor, Compare with menu item). Actions can be categorized as follows:

  • Insert actions - available if the target item does not exist

  • Replace actions - available if target is an overwritten Work Item

  • Delete actions - available if the source item does not exist in the target Document, or is in the Recycle Bin.

  • Referencing actions - available for Work Items.

    Available when the target Work Item is referenced from the source Document or when the target Work item branched from source Work Item and has been overwritten."

  • Field actions - available for Work Item fields.

    Available when Work Items have differences at least in one field that is valid for merging.

For any selected Document or Work Item, the Merge sidebar displays only those merge actions that are valid for the selection in each merge direction. However, project mangers can opt to disallow some action(s), and an Administrator can change the Merge Actions configuration so that disallowed actions are never available in the sidebar. Therefore, you might not see some of the actions listed in this reference. It can be helpful to review the topic on Merge Teminology before proceeding.

Insert Actions

Insert actions are available if an item in the source Document does not exist in the target Document.

  • Insert Live Reference: Insert Work Item as a "live" referenced Work Item. Subsequent changes to the original will propagate automatically. Available if an item in the source Document does not exist in the target Document.

  • Insert Frozen Reference: Insert Work Item as a referenced Work Item "frozen" to the current revision of the source item. Subsequent changes to the source item will NOT propagate automatically. It will be possible to manually update the reference to some future revision of the source item. Available if an item in the source Document does not exist in the target Document.

  • Copy the Work Item: Copy the Work Item to the target Document creating a traceability link to the source Work Item. Item in the target Document will be a static copy, not a reference. Never updated unless manually replaced by another copy. Available when a Work Item in the source Document is selected for merging, and the target Document contains no copy of or reference to the source item.

Replace Actions

These actions are available if the target is an overwritten Work Item.

  • Replace Overwritten Work Item with Live Reference: Send an overwritten Work Item in the target Document to the Recycle Bin, and replace it with a "live" referenced Work Item. Subsequent changes to the referenced item will propagate automatically.

  • Replace Overwritten Work Item with Frozen Reference: Send an overwritten Work item in the target Document to the Recycle Bin, replace it with a referenced Work Item from the source Document, and freeze the reference to the current revision of the source item. Subsequent changes to the source item will not propagate. It will be possible to manually update the reference to some future revision of the source item.

Delete Actions

  • Delete Reference: Delete the referenced Work Item from the target Document. Available if target item is a reference to a Work Item that does not now exist in the source Document.

  • Send Item to Recycle Bin: Remove Work Item from the target Document but keep it in the Recycle Bin. Available when the target item is not a referenced Work Item.

  • Delete Work Item: Delete Work Item from the Document and the repository (but not from History).

    This action is disabled by default, and not visible to users. Allowing deletion of Work Items should be considered carefully. It may not be acceptable in regulated industries where process transparency and proof of compliance are required. If project management decides to allow it, the action can be enabled by an administrator in the Merge Actions configuration.

Referencing Actions

  • Freeze Work Item Reference: Freeze the Work Item reference in the target Document at a specific revision of the source item. Available when the target item is referenced from the source Document.

  • Unlink and Insert Live Reference: Insert Work Item as a "live" referenced Work Item. Subsequent changes to the original will propagate automatically. The existing traceability link between the source item and the target item will be removed. Both the existing target Work Item and the new referenced Work Item will appear in the target Document. Available when target is an overwritten item from source Work Item.

  • Unlink and Insert Frozen Reference: Insert Work Item as a referenced Work Item "frozen" to the current revision of the source item. Subsequent changes to the source will NOT propagate automatically. The existing traceability link between the source item and the target item will be removed. Both the existing target Work Item and the new referenced Work Item will appear in the target Document. Available when target is an overwritten item from source Work Item.

Merge Fields Actions

Merge fields actions are available if the merge target is a Work Item and...

  • Target Work Item is one that was branched and then overwritten in the branch, or...

  • Source Work Item is frozen to a revision, and target Work Item is contained in the target Document (i.e. not referenced) and source and target Work Items have field changes that can be merged.

Actions:

  • Merge Some Fields: Merge fields specified in the Merge Actions configuration. By default this includes Title, Description and Test Steps, but this can be changed by an Administrator.

  • Merge All Fields: Merge all fields of the Work Item that are supported for merging.

Fields Not Supported for Merging

When the Merge All Fields merge action is selected, all fields are merged in addition to Title and Description except the following fields:

  • Comments

  • Project

  • Module

  • Author

  • Created

  • ID

  • Status

  • Resolution

  • Updated

  • Location

  • Planned Start

  • Planned End

  • Outline Number

  • Linked Work Items Derived