Editing a Document

After creating a Document, either in the portal or by importing, you can edit it in the Document Editor. You will see much that is familiar to you from your desktop application, or if you have used an online tool like Google docs. The major difference, conceptually, is that some of your Documents' content can be marked as Work Items. This approach provides the benefits of both office documents and data-driven process and project management for the organization. People like business analysts and requirement engineers whose work typically focuses around documents don't have to change their paradigm or give up much in terms of functionality and ease of use. People on the technical side get the workflow and data-driven management capabilities they need. Executives and others responsible for compliance issues get the information they need. The organization as a whole benefits from improved efficiency, transparency, and communication.

This section focuses on various features and capabilities you will encounter while editing Documents. See also: User Reference: Documents Reference: Document Editor Toolbar.

Find and Replace

The Document Editor has its own Find and Find and Replace that even work for text within the Work Items contained in a document.

They behave a little differently if On-demand Work Item Loading is set to ON or OFF for the document you're working with.

On-demand Work Item Loading OFF

  1. Click Find and Replace in the Actions Menu or use the CtrlH keyboard shortcut.

    (Clicking CtrlF with On-demand Work Item Loading OFF will launch the Browser's native "Find" dialog.)

  2. Enter an item to search for in the "Find" field.

  3. (Optional). Tick to only display results with the same capitalization.

  4. Cycle through the results by clicking Next> and <Previous.

  5. Click Replace to replace the highlighted item with the text in the "Replace with" field or Replace All to replace all occurrences within the document.

  6. If Replace All is clicked another dialog appears showing the results.

    Note

    If there is a discrepancy between the number of items found and replaced, it is because uneditable items (referenced Work Items, TOC entries etc.) cannot be replaced.

With On-demand Work Item Loading ON

Because On-demand Work Item Loading only renders the sections of a document that a user scrolls to, attempting to use the browser's native "Find" (CtrlF) would lead to incomplete searches. To ensure that all data in a document and the Work Items it contains is searchable, Polarion has its own "Find" function for CtrlF, or Find icon in the Actions Menu, when On-demand Work Item Loading is ON.

(If you use CtrlF, click on the Document first. If the focus is on the Navigation bar, sidebar or browser window, the browser's internal "Find" command will be launched instead.)

Find
  1. Click the Find in the Actions Menu or Press CtrlF.

  2. Polarion automatically begins searching the document, and displays a percentage of its progress. When complete, the total number of matching results is displayed and the current occurrence highlighted.

  3. Cycle through the results by clicking Next> and <Previous.

  4. (Optional). Tick to only display results with the same capitalization.

  5. CtrlH turns an open "Find" dialog into "Find and Replace".

Replace & Replace All
  1. Click the Find and Replace icon in the Actions Menu or the CtrlH keyboard shortcut.

  2. Enter the text to replace in the “Find” field.

  3. Polarion automatically begins searching the document, and displays a percentage of its progress.

  4. Once complete, it lists the total number of times the item appears and the occurrence number that's currently highlighted.

  5. (Optional) Tick the to only display results with the same capitalization.

  6. Cycle through the results by clicking Next> and <Previous.

    Click Replace to only replace the currently highlighted item, or Replace All to replace all matching occurrences.

Internet Explorer Limitations
  • With Internet Explorer, Find and Replace does not automatically jump to the first occurrence. Just click Next> to do so.

  • Uneditable text is counted and tracked, but not highlighted.

Copy and Paste

Because Documents are "artifact-aware", that is, they contain Work Items which are tracked and managed with other tools, the common actions of cutting/copying and pasting of text require some special considerations and processing behind the scenes. You should keep the following points in mind when performing any type of cut-copy-paste actions in Documents.

In general, cut/copy and paste between different Documents (also between different projects) will just copy the rich text to the destination, except when copying Work Items.

  • Headings are preserved, but new Heading objects are created.

  • If copy and pasting from an existing Work Item, the target document will the option to select a "Referenced" Work Item or a New Work Item appears.

  • If copy and pasting from an Unsaved Work Item, the target document will contain a new Work Item with only the text selected copied.

  • Tables and their content are preserved

  • Table of Contents included in cut/copy is removed on paste. The TOC will need to be recreated in the target Document.

  • Wiki content inserted in the Document is copied and pasted without alteration. If the Wiki content source contains relative paths, these could become invalid in the target Document and you would need to modify them manually.

  • Links are copied/pasted without alteration. If links contain relative paths, the paths might not be valid in the target Document and you would need to update them manually.

  • If cut/copied text contains comment markers, these are dropped on paste to the target Document.

Pasting Images from Clipboard

With some limitations (see Note below) you can paste an image from your clipboard into the Document body or into the descriptions of Work Items in the Document. If there is a mixture of images and text in the clipboard, then only the name of the image file is pasted, and not the image itself. When you past an image, an attachment is automatically created with file name screenshot-[timestamp].png, where [timestamp] is the date-time when the image was pasted. Supported image formats are: BMP, JPG, PNG, and GIF.

To paste an image from your clipboard, simply locate the insert point where you want to image to appear in the Document and use your browser's Paste keyboard shortcut or menu command.

Note

Quality of the pasted image can vary depending on whether you copy the image from your file system, a web browser, a photo viewer, or image management program, as well as which supported browser you are using.

Cut Copy and Paste Within a Document

While working on a Document you may decide to change the structure and flow of the Work Items. You might want to cut an entire Work Item and paste it elsewhere in the Document, or copy a Work Item, past it as the basis for a new item, modifying the text after pasting. To facilitate these actions the Document Editor provides Copy and Cut commands on the Work Item icon menu which appears to the left of the Work Item title, just outside the page border.

The Cut command selects the entire Work Item and cuts it to the clipboard, visually removing it from the Document. You can use Undo to restore the cut item to the Document.

The Copy command selects the entire Work Item and copies it to the clipboard, leaving the Work Item content highlighted in the Document.

After copying or cutting a Work Item using the respective menu command, move the insertion point to the line where you want to paste the item and use your browser's Paste command or keyboard shortcut to paste from the clipboard.

TIP

You can always use your pointing device to select text or a Work Item, and use your browser's keyboard shortcuts to cut, copy, and paste the selection. The menu items described above merely make it easy to accurately copy or cut an entire Work Item.

Spellcheck

Polarion LiveDoc Documents use your browser's built-in spellchecking feature to check spelling in text and Work Items. Be sure you are familiar with this feature of your web browser and that it is enabled.

Spellcheck and Performance

A known issue in very large Documents is that browser-based spell checking may negatively impact performance of the Document Editor or result in memory-usage errors. This has been observed most often with Microsoft Internet Explorer and Firefox. If you encounter such problems with a Document, you may need to disable your browser's spell check feature while editing it.

Keyboard Shortcuts

Keyboard shortcuts in the Document Editor are similar to those of applications such as Microsoft Word and Google Documents. The same shortcuts apply in the Description field and other rich-text type fields in Work Items. A comprehensive reference dialog, context-sensitive for your operating system, is available via the Keyboard Shortcuts item on the Help menu of the respective editors.

Figure 15.20. Keyboard Shortcuts - Document Editor

Keyboard Shortcuts - Document Editor

How to access Keyboard Shortcuts reference dialog in Documents

Work Items in Documents

Any time during the authoring process of a Document, you can mark some parts of its content as Work Items. Marking content creates a Work Item artifact in the underlying repository, enabling the team to take advantage of all the traceability, workflow, reporting, and other management features. Document authors can continue to work with content in a straightforward document-like editor.

By default, Documents can contain Heading type Work Items, used to display the structure of the Document in the Tree view, and one other user-defined type, used for creating Work Items that are tracked, processed, and managed with workflow. The user-defined Work Item type is specified when the Document is created. After the Document is created, one or more additional user-defined Work Items types can be configured, enabling users to mark Document content as a Work Item of any of the configured types. For example, a team might choose to have requirements and test cases in the same Document. (See Multiple Work Item Types in this chapter for specifics on how to set up a Document to contain multiple Work Item types.)

You must have permissions to modify Documents and to create new Work Items as well as modify Work Item fields. If you are denied permission to MODIFY any fields, some restrictions on creating new Work Items are imposed. For details, see the User Reference topic Work Item Field Permission Restrictions: New Work Items.

Marking Document Content as Work Items

To mark Document content as a Work Item:

  1. Select all the text you want included in the Work Item. If you select multiple paragraphs, they will all be included in the same Work Item.

  2. On the Document toolbar, click the Work Item type icon. A drop-down menu appears.

  3. Select the desired Work Item type from the menu. The selected text is marked as a Work Item, and the icon for the specified type appears just outside the left-hand border of the editor. The artifact in the underlying repository is not created until you save the Document.

If you change your mind, you can unmark the content by clicking on its type icon and choosing Unmark from the pop-up menu. If you want to unmark the item and delete both Document content and the underlying artifact, choose Delete instead.

Modifying Work Items

After a Work Item is created, you can generally edit its description, and other properties such as fields and links. However, your user profile must be granted permission to MODIFY Work Items, and Work Item fields. If you are denied permission to MODIFY any fields, you cannot edit Work Item content in the Document Editor. You must use the Table view, where you will be able to modify only those fields you have permission to MODIFY. If you find you are restricted from editing Work Items, contact your project administrator to review your permissions.

Structuring a Document's Work Items

Creating hierarchically structured Work Items is as easy as using different indent levels. For example suppose you have two paragraphs marked as Requirements, and the second paragraph is a sub-requirement of the first. Simply indent the second paragraph. Behind the scenes, Polarion automatically takes care of linking the two Work Item artifacts with the correct link role, and people viewing them in the integrated Tracker will see the links and the relationship.

If you change your mind and decide the two paragraphs are not hierarchical, simply un-indent the child paragraph and save the Document. Again, all linking operations of the underlying artifacts are handled automatically. You simply keep working with your document.

Suppose you have two paragraphs marked as Requirements and you decide that the second Requirement is neither a sub-requirement, nor a separate requirement, but rather part of the first. Simply merge the two paragraphs just as you would with paragraphs or bullet-list items in Word. The content of the second Requirement is automatically unmarked as a Work Item, any structural linking is removed, and the content appears as part of the first Requirement. If the Document was saved after the second Requirement was created, then after the merge the underlying Work Item artifact is still maintained in the underlying repository and appears in the Recycle Bin pane of the Document sidebar. This enables maximum flexibility during the Document's development process. For example, you may later decide that a merged Requirement actually belongs in a different Document. You could delete the relevant paragraph from the combined Work Item, and move the original Work Item (now in the Document's Recycle Bin) to the other Document. When the Document is near completion, you can clean up any Work Items in the Recycle Bin that you are sure you no longer need. For information see Recycle Bin later in this chapter.

You can also move content marked as a Work Item within the document via Cut/Paste. It works just like moving content in Word. Simply select the entire text of the marked Work Item, cut it to your clipboard, and paste it back into the Document wherever you want it.

Using the Tracker Interface

If you are viewing a Document's Work Items in the Work Item Tracker (Navigation: Work Items), you can modify the structure of the items using that interface. You can:

  • Move an existing Work Item so that...

    • ... it is the first or last child of another Work Item in the same Document.

    • ... it is placed before or after another Work Item in the same Document, under the same parent item.

  • Create a new child Work Item as last child of the current Work Item in the same Document.

  • Create a sibling Work Item on the same hierarchical level as the current Work Item in the same Document.

To move an existing Work Item:

  1. Select it in the Table view.

  2. On the Work Item Editor toolbar invoke Actions > Move.

  3. In the Move Work Item(s) dialog, use the In Document Structure option to specify where you want to move the current Work Item.

Note

The move operation moves any existing sub-tree, not just the selected item(s).

Both contained and referenced Work Items can be moved within a Document using the Table interface.

See also: Moving Work Items.

To create a new sibling Work Item:

  1. Select an item in the Table view that is on the same hierarchical level as the new item you want to create.

  2. On the Work Item Editor toolbar invoke Actions > Create Sibling Work Item

  3. On the sub-menu, select the type for the new item. The menu enables you to select only the type(s) configured for the Document that contains the currently selected Work Item. For example, if the Document is configured to contain only Requirements, that will be the only sub-menu item. If it is configured to contain Requirements and Tasks, both will appear as sub-menu items.

Linking a Document's Work Items

You can link the Work Items defined in a Document to other items in the same Document, in a different Document, or stored directly in the Tracker. Links can denote structure and provide traceability. For example, in a requirements specification Document, Requirement type Work Items may be structured with parent-child relationships where one requirement is the parent of one or more additional requirements. This type of structure is most easily and naturally done with hierarchical headings and/or indentation (of bullet list items, for example). For information, see Structuring a Document's Work Items.

Linking for traceability may require linking Work Items defined in the Document to Work Items in a different Document, or existing in the integrated Tracker. For example, you would probably want to link the Requirement type Work Items in a requirements specification Document to the Test Case type Work Items that verify the requirements. The Test Case items might be defined in another section of the same Document, in another Document, or created directly in the Tracker. For more complete information on this important topic, see User Guide: Linking Work Items.

This section explains how link Work Items to each other in the same Document, Work Items in one Document to items in a different Document, and Work Items in a Document to Work Items in the Tracker.

TIPS

If you make a mistake it's not a problem. No links are created in the system until you save the Document in which you originate the link(s). If you accidentally create a pending link to a wrong target item, you can click the X icon in the link detail panel and then confirm the prompt to cancel changes. You can then begin the linking operation again.

When linking to multiple Work Items, you can specify a different link role for different target items. For example, you might link from a requirement to a test case with a "verifies" link role, and to another requirement with a "refines" link role. You select the link role in the link detail panel after clicking the link icon on each target Work Item.

Linking Within One Document

You can link one Work Item in a Document to another single item, or several target Work Items in the same Document all at once. For this operation, you only need one browser tab or window.

Figure 15.21. Single Document

Single Document

Link Work Items in the same Document by clicking the Link icon on the source and target items

To link Work Items in the same Document:

  1. Click on the icon in the left margin of the Work Item you want to link to some other Work Item. The link detail panel appears.

  2. In the link detail panel, select the link role for the link you are creating. This describes the relationship of the source item to the target item(s)... "Relates to" or "Depends on", for example.

  3. Locate the first Work Item you are linking to, and click the Link icon to the left of it.

    If you want to link to multiple Work Items, hold down Ctrl (Windows) or Command (Mac and others), and click the (Create Link) icon of each target Work Item. The panel reports the items linked each time you click.

  4. Save the Document. The links are not saved in the repository or the Document history until you save.

You can view the items to which any Work Item is linked by clicking on the item in the Document and opening the Work Item Properties pane of the Document sidebar.

Linking Across Different Documents

You can link a Work Item in one Document to another single item in a different Document, or to several target Work Items in a different Document all at once.

TIP

This linking is easiest if you open 2 browser tabs or windows: one displaying the Document containing the Work Item(s) you want to link (referred to as "Tab 1"), and the other ("Tab 2") displaying the Document or Tracker view containing the Work Item(s) you want to link to.

To link Work Items in different Documents:

  1. In one browser tab or window ("Tab 1"), open the Document containing the Work Item(s) you want to link.

  2. In a second browser tab or window ("Tab 2"), open the Document containing the target Work Item(s). That is, the item(s) you want to link to from some item(s) contained in the first Document (in Tab 1).

  3. In Tab 1, select a Work Item to link by clicking on the (Create Link) icon in the item's left margin. The link detail panel appears in both browser instances.

  4. In the link detail panel, select the link role for the link you are creating. This describes the relationship of the source item to the target item(s)... "Relates to" or "Depends on", for example.

  5. Switch to Tab 2. If you want to link the item in Tab 1 to multiple items in Tab 2, press and hold Ctrl or Command (depending on your operating system).

  6. Click the (Create Link) icon beside the first target Work Item in Tab 2. To link to one or more additional items in this target Document, click their link icons while continuing to hold down the Ctrl or Command key.

  7. Switch back to Tab 1 and save that Document (the one from which you started the link operation) to create the links in the repository and Document history.

TIP: Link and Create New Items

You can link new Work Items in a target Document "on the fly". When you begin a link from a Work Item in one Document (in Tab 1), then if you switch to a different Document (in Tab 2), and you create new Work Items there, links to the new items will be automatically created and added in the link detail panel.

TIP: Links to Historical Revisions

You can link a Work Item to one or more items in a historical revision of a target Document. For example you might link the current revision of a Business Case to the version of a Requirement in a functional specification Document saved in a Baseline. To do this, open in Tab 2 the Baseline containing the revision of the Document, and then open the Document containing the items you want to link to.

Linking from Document to Tracker

You can link a Work Item contained in a Document to one or more Work Items in the Table view of the Tracker. You can link to a single target item, or multiple target items at once. As in the previous section, you should use 2 browser tabs or windows.

To link a Document Work Item to Work Items in the Tracker:

  1. In one browser tab or window ("Tab 1"), open the Document containing the Work Item(s) you want to link.

  2. In a second browser tab or window ("Tab 2"), open the Table view (Navigation > Work Items), and run a query to retrieve the target Work Item(s) and list them in the table.

  3. In Tab 1, select a Work Item to link by clicking on the (Create Link) icon in the item's left margin. The link detail panel appears in both browser instances.

  4. In the link detail panel, select the link role for the link you are creating. This describes the relationship of the source item to the target item(s)... "Relates to" or "Depends on", for example.

  5. Switch to Tab 2. If you want to link the item in Tab 1 to multiple items in Tab 2, press and hold Ctrl or Command (depending on your operating system).

  6. In the table in Tab 2, locate the first target Work Item and click the (Create Link) icon on its row in the table. To link to one or more additional items in the table, click the link icon on their respective table rows while continuing to hold down the Ctrl or Command key.

    Note that each target item can be linked with a different link role. Change the role in the link detail panel after Ctrl/Command clicking an item.

  7. Switch back to Tab 1 and save the Document to create the links in the repository and Document history.

TIP

You can link Work Items using other tools in the Polarion portal. You can use the Linked Work Items section in the Work Item editor (Navigation: Work Items: Table view). If your license provides the feature, you can also link Work Items in the Matrix view.

See also:

Multiple Work Item Types

By default, Documents contain only one Work Item type - Requirements, for example. You specify this type when creating a new Document. However, it is possible for Documents to contain more than one type. For example, you might want a Document to contain requirements in one part, and test cases in another part. Assuming that such a document was created specifying the Requirement type, you would need to add support for the Test Case type before you could mark content as Test Case type Work Items.

To add support for another Work Item type:

  1. Click the Work Item Type drop-down list control in the Document editor toolbar (see figure below).

  2. On the drop-down menu, choose Configure Presentation. The Configure Work Item Presentation dialog appears (see figure below). The dialog presents a table showing the Work Item types currently supported in the Document.

  3. On the last row of the table, click the Type list and select the Work Item type you want to be able to define in this Document.

  4. Fill in the fields in the remaining columns as desired (consult the User Reference topic: Configure Work Item Presentation Dialog if necessary).

  5. If you wish to add support for another type, click the icon in the Actions column. A row is added to the table.

  6. Repeat these steps until you have added support for all the Work Item types you want in the current Document. Click OK when finished.

Figure 15.22. Configure Work Item Presentation Dialog

Configure Work Item Presentation Dialog

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

See also: User Reference: Configure Work Item Presentation Dialog, User Guide: Showing Data Field Values, and User Guide: Changing Work Item Type.

Referenced Work Item Types

You can insert referenced Work Items from some other Document into the Document you are editing. Referenced items are contained in another Document in the same project or another project, and they appear "read-only" in the current Document. Sometimes, such referenced Work Items may be of a type not configured in the Document's Work Item presentation, or even in the project where the Document lives. Polarion supports two main scenarios:

  1. Referenced from same project, but current Document presentation is not configured with the referenced type: In this case, the Document presentation configuration is automatically updated to add the referenced type. By default, the added type is marked as Hidden in the Work Item Presentation dialog. When so marked, the type does not appear in the Configure menu and users cannot mark items contained in the Document as the newly added type. It is possible to clear the Hidden option in the Work Item Presentation dialog, enabling users to mark Work Items as the new type.

  2. Reference from different project, and referenced type is not defined in current project: In this case, the Document presentation configuration is automatically updated to add the referenced type, the added type is marked as Hidden in the Work Item Presentation dialog and cannot be unmarked unless the same type is defined in the current project. The type icon from other project is not shown.

As an example, suppose there is requirements project having a requirements specification Document configured to contain Requirement type Work Items, and another project having a test specification Document configured to contain Test Case type Work Items. Now suppose you want to insert into the requirements specification Document some Test Case type items referenced from the test specification Document, but the requirements specification Document's presentation is not configured to support Test Case type items - in fact, that type is not even defined the requirements project. When a referenced Work Item is inserted via the Configure menu, Polarion automatically updates the Document presentation configuration if necessary to allow the referenced Work Item type (i.e. Test Case) to appear in the Document. The properties of the added type (Label, Content, Fields, etc.) can be edited in the Document Presentation dialog.

Accessing Work Item Properties

The Document Sidebar provides the Work Item Properties panel, which enables you to edit data fields and access links of Work Items defined in the Document.

You can specify which Work Item fields appear in the Properties section of the panel. When the Properties panel is showing, click the icon (Pane Settings) icon and choose Select Fields on the menu. In the Select Fields dialog, check the boxes of the Work Item fields you want to be able to edit in the Document, and clear the check boxes of fields that should not be shown there. You can also control the order in which the fields display in the panel by rearranging their order in the dialog.

Some Work Item fields, both standard and custom, may be configured as required fields. A value must be supplied in all required fields before a new Work Item can be saved. When you mark a new Work Item in a Document, if any required fields are not among those shown in the Work Item Properties panel, then a default value is automatically and silently set for these fields. This default may or may not be what you actually want, so it is usually a good idea to make sure that all required fields appear in Work Item Properties panel of the Sidebar. You can easily see which fields are required by looking at any Work Item in the Table view of the Document. Fields marked with a red asterisk (s) are required fields. Be sure to check the Custom Fields section to see if any custom fields have been configured as required fields.

TIP

Note that all the fields of any Work Item can be edited in the Table view of the Document, which you can launch from the Document Editor toolbar. Remember also that you need user permissions that enable you to edit Work Items in order to change Work Item properties in a Document.

To access properties of a Work Item in a Document:

  1. Click the Work Item's icon next to the left-hand border of the Document Editor.

  2. On the pop-up menu choose Properties.

The Work Item Properties panel of the Sidebar displays properties of the currently selected Work Item in the Document. The data fields of the selected Work Item appear in the Properties section as a set of drop-down list controls. After changing field values, be sure to save the Document.

The Links section appears below the Properties section. It shows the items currently linked with the selected Work Item.

Locating Referenced Work Items

Not all Work Items appearing in a Document are necessarily contained in it. Some may be contained in another Document and just referenced in the current one. If the currently selected Work Item is referenced from another Document, the Work Item Properties panel of the Sidebar contains the Documents section, which lists the source Document (i.e. the one that actually contains the item, and in which it can be edited), and all Documents that reference the Work Item. Names of Documents are clickable links the open the respective Document in the Document Editor. For more information on referenced Work Items, see the User Guide topic Branching Documents. See also User Reference: Documents: Document Sidebar: Work Item Properties Panel.

TIP

If you find you cannot edit a Work Item, it may be referenced from a different Document. Check the Work Item Properties panel. If the item is referenced, you can only modify it in the source Document, and you must have the necessary permissions for editing Work Items in that Document.

Editing Work Item Links

To access the links of a Work Item defined in a Document:

  1. Select a Work Item by clicking anywhere in its title or description text.

  2. In the icon's pop-menu, choose Properties. The sidebar opens (if not already open) and displays the Work Item Properties panel. Any existing links appear in the Links section.

The items listed in the Links section are clickable hyperlinks that switch the selection in the Document body to the linked Work Item, if the linked item is contained in the Document. If the item is external to the Document, the linked item opens in a new browser tab or window.

Linking Work Items in One Document

The Work Item linking feature provides a quick way to link Work Items contained in the same Document. To create a link this way:

  1. In your Document, navigate to the Work Item you want to link and click the (Create Link) icon to the left of the Work Item's icon.

  2. In the pop-up dialog, select the Link Role for this link (Relates to, for example).

  3. Locate the target Work Item you want to link to, and click its (Create Link) icon to complete the link definition.

  4. Save the Document to actually create the link in the repository and the Work Item history.

Linking Between Documents

You may want to link Work Items defined in one Document to Work Items defined in another Document. For example, Requirement items on a requirements specification Document might be linked to Test Case items in a test specification document. This example will be used to describe how to link Work Items in different documents.

To link Work Items in 2 Documents:

  1. Open both documents (e.g. "Requirements Spec" and "Test Spec") in separate browser tabs or windows. (Using two windows placed side by side can help you visualize the linking process.

  2. Assume an example of a requirement Work Item in a "Requirements Spec" document, which needs to be linked to a test case Work Item in a "Test Spec" document. In the "Requirement Spec" document, find the requirement Work Item you want to link, and then click the (Create Link) icon in the margin to the left of the Work Item's icon.

    TIP

    Although not necessary, you may find it helpful to click on the Work Item to select if before beginning the linking operation.

  3. In the pop-up dialog, select the Link Role for the link (Is Verified By, for example).

  4. Switch to the browser instance displaying the second Document ("Test Spec") and locate the test case Work Item that will be linked to the requirement.

  5. Click the (Create Link) icon for the target Work Item to finish defining the link.

  6. Save the Document from which you started the link operation to create the link in the repository and the history.

Using the Linked Work Items Dialog

Use the Edit Links button in the Properties page of the Document sidebar to launch the Linked Work Items dialog. There you can manage the links of the currently-selected selected Work Item in your Document. You can use the dialog as an alternate way to add one or more links to a selected Work Item, as well as to edit some properties of existing links, or remove some existing links. For details about this dialog, please see User Reference: Linked Work Items Dialog

Showing Data Field Values

Whenever you mark Document content as a Work Item, Polarion creates a Work Item artifact in the repository. Each Work Item artifact has a number of standard data fields. It is also possible to configure custom data fields. You can optionally show the value one or more Work Item data fields along with the text of Document elements marked as Work Items. For example, you might decide to show such data as status, priority, or assignee. When you configure data fields for the Work Item types in your Document, Work Item data appears in your online Document, and in exported copies, but is not really part of the content. It is actually maintained in the underlying repository and simply displayed in your document. You can see the same fields as part of the Work Item detail if you view the item in the integrated Tracker (in Navigation > Work Items > Table, for example). Values for the ID and Status fields are pre-configured to appear by default. You can either remove these from the visual presentation, or add additional fields.

To configure display of data field values in a Document:

  1. Click the Work Item Type drop-down list control in the Document editor toolbar.

    Figure 15.23. Configure Work Item Presentation Dialog

    Configure Work Item Presentation Dialog

    Configuring the Work Item type(s) a Document can contain

  2. On the drop-down menu, choose Configure. The Configure Work Item Presentation dialog appears. The dialog presents a table showing the Work Item types currently supported in the Document.

  3. Locate the row for the Work Item type you want to configure. For example, if the table contains rows with presentation configurations for Requirement, Test Case, and Defect types, and you want to specify the fields to show with Requirement type items, you will need to work with fields in the row for Requirement.

  4. Click the Select Fields button, and in the Select Fields dialog, add the fields you want to appear in the Document from the list on the left to the list on the right. You can optionally set whether to display fields at the start or end of Work Items. For more information, see the User Reference topic Configure Work Item Presentation Dialog.

    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.

See also: User Reference: Configure Work Item Presentation Dialog, Multiple Work Item Types.

Using Outline Numbering

With Document Headings

Outline numbering adds numbers to document headings.

When Importing a Word document, Outline Numbering is enabled by default .

(See below to disable Outline numbering for imported documents.)

  1. Click () on the Document Toolbar.

  2. Click () Document Properties in the drop-down menu.

  3. Select whether to turn Outline numbering ON or OFF .

    Figure 15.24. Enable / Disable Outline Numbering for Headings

    Enable / Disable Outline Numbering for Headings

    NOTE: Entering a Prefix: will only add a prefix to Work Items within the heading. (Visible in Enable / Disable Outline Numbering for Headings Tree View )

  4. Click

With Work Items

Polarion can also automatically add outline numbers to all Work Items within a document.

  1. Select an existing Work Item or locate the insertion point on an empty line.

  2. Click the Work Item Type selector icon in the document toolbar.

    Figure 15.25. Work Item Selector

    Work Item Selector

    (Note: The Work Item Icon will vary according to the current Work Item types within the document.)

  3. Choose Configure. The Configure Work Item Presentation dialog appears.

  4. For every Work Item type in the table (there is one per row), click Select Fields. Then, in the Select Fields dialog, add Outline Number to the list of fields on the right.

  5. (Optional) You can edit the order that the selected fields will appear if the Show Fields at End as Table option in Step 6 is selected by using the keys. (The field at the top of the list appears at the top of the table.)

  6. Select a layout option:

    - Show in Sidebar only (Outline numbers only appear in the Document Properties, Work Item Properties and Document Outline Sidebars.)

    - Show in Document only (Outline numbers only appear in the document.)

    (This only applies to the Work Item and Document sidebars. Outline Numbers ALWAYS appear in the Document Outline Sidebar.)

    - Show in Sidebar and document (Outline numbers appear in both the document and respective sidebars.)

    (An additional Show at option appears letting you select whether to show the outline numbers Before or After the Work Item.)

    - Show Fields at End as Table (Displays any field with selected in a table at the end of the document.)

  7. Click Set as Default, then click OK .

    User Specific Outline Numbering

    To set a personal, user based preference for Work Item outline numbering:

    a) Click on the Work Item sidebar ( --> "Work Item Properties")

    b) Click Select Fields.

    c) The Configure Work Item Presentation dialog will appear but will contain an additional Set as Personal button beside Set as Default.

    (The Reset button resets any field customization to the default settings.)

Work Item Recycle Bin

When some Document content is marked as a Work Item, a Work Item artifact of a specified type is created in the underlying repository. During editing of a Document, authors or editors may decide to unmark some content so that it is no longer a Work Item, or (more likely) to merge one Work Item paragraph or section into the preceding Work Item content. In such cases, the Work Item content either no longer appears in the Document, or it no longer appears as a separate Work Item. However, the artifact still exists in the underlying Repository. This means that it is subject to workflow, planning, auto-assignment, or any other Work Item and process management features and actions. In the early stages of the Document's development, having such "orphaned" Work Items in a Document may be perfectly acceptable because you might still want to do something with them - put them back into the Document later, or put them into another Document, for example.

The Document Sidebar's Recycle Bin panel shows any Work Items that exist in the repository, but are no longer present in the Document. (You will also see these items in the Table view of the Document. This view contains a button Open in Document's Recycle Bin which alerts any viewer to its state, as well as providing access to it in the Recycle Bin.) The Recycle Bin provides you with some options for handling these stored but unused Work Items. When you think a Document is complete, or nearing completion, it is a good idea to check the Document's Recycle Bin and clean up any Work Items shown there so as not to clutter the integrated Tracker with Work Items that are not intended to be processed.

To access a Document's Recycle Bin:

  1. In the Document toolbar, click the Sidebar icon to invoke a drop-down menu.

  2. On the drop-down menu, choose Recycle Bin to display the sidebar's Recycle Bin panel.

The Recycle Bin panel provides several options for cleaning up Work Items in the Recycle Bin:

  • Reinsert Work Item(s) into the current Document

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

  • Disassociate Work Item(s) from the Document but keep them in the project, to be accessed only via the Tracker (i.e. the Work Items topic in Navigation).

  • Delete Work Item(s) from the repository.

TIP

For the procedures in the rest of this topic, you may find it useful to view User Reference: Document Sidebar: Recycle Bin Panel.

For a reference on what actions send content to the Recycle Bin, see sub-topic of the above: Content Handling.

To reinsert a Work Item from the Recycle Bin into the current Document:

  1. Place the insertion point (caret) at the position where you want to insert the Work Item(s).

  2. In the Recycle Bin, select the item(s) you want to insert by checking the box preceding the ID-Title.

  3. Click the Insert button to insert the selected Work Item(s) into the Document at the current insertion point.

  4. Save the Document.

To move a Work Item from the Recycle Bin to a different Document:

  1. In the Recycle Bin pane of the Sidebar, select the item(s) you want to move by checking their boxes.

  2. Click the Move button. The Move Work Items dialog appears.

  3. In the dialog, select the Move selected Work Item(s) to Document option.

  4. In the Space list, select the name of the space where the target Document resides. (Default selection is the space of the current Document). The Document list is populated with the names of the Documents residing in the selected space.

  5. In the Document list, select the name of the target Document, click OK, and finally Save the Document. The orphaned Work Items are disassociated from the current Document, removed from the Recycle Bin, and associated with the target Document, to which the content is appended.

To disassociate a Work Item from the Document but keep it in the project:

  1. In the Recycle Bin panel of the Sidebar, select the item(s) you want to move by checking their boxes.

  2. Click the Move button. The Move Work Items dialog appears.

  3. In the dialog, select the Move selected Work Item(s) out of Document option, click OK, and then Save the Document.

    The selected Work Items are disassociated from the current Document and removed from the Recycle Bin. However, the data artifacts are maintained in the repository with their same IDs and properties. People using the integrated Tracker will be able to manage them as Tracker-based Work Items.

To delete Work Items from the Recycle Bin and the repository:

  1. Select the item(s) you want to delete by checking their boxes.

  2. Click the Delete selected Work Items button and respond to the confirmation prompt.

  3. Save the Document.

Note

You can delete a Work Item without first moving it to the Recycle Bin: click the Work Item icon in the left margin and select Delete on the menu. The item is deleted from the Document and the repository. (It is not deleted from the Document history.)

If you want to delete a Work Item that is not defined in a Document, see User Guide topic: Work Item Actions: Deleting Work Items.

Filtering Work Items in Documents

You can filter a Document to show only a subset of all the Work Items it contains. For example, a specification might contain requirements for the same feature, but on different operating systems. Assuming a custom field "OS" to designate the operating system, you could filter the Document to show only requirements for, say, Ubuntu Linux, by querying on the custom field.

Filtering is accomplished using the integrated query engine and query language. The Query Builder tool is available to help you construct simple or complex queries graphically if you are not familiar with the query language syntax.

To filter a Document to view a subset of its Work Items:

  1. On the Document toolbar, click Actions Menu > Filter. The document becomes read-only, and filter controls appear in the Document toolbar.

  2. In the Filter Work Items field, enter the visual query elements and/or query syntax required to obtain the results you want: OS:Ubuntu, or severity:must_have, for example.

TIPS

You can also filter Work Items when viewing any revision of a Document in the Document history.

If an item shown by the filter is the child of one or more other items, the parent items are also shown in the Document regardless of whether or not the match the filter criteria.

While viewing the Document in its filtered state, you cannot edit the text. However, you can:

  • Access the Document history and compare revisions.

  • View and edit Work Item properties and links in the Document sidebar.

  • Export the filtered Document using Word Round-trip > Export Document. Only the Work Items shown by the filtering are included in the exported document.

  • Print the Document or export it to PDF. Only the Work Items shown by the filtering appear in the printed copy or exported PDF file.

  • Reply to any comment that is shown when the filtering is engaged (but not create new comments).

  • Access linked Work Items that are hidden by the filter. Linked items appear in the Properties of Work Items shown by the filter and if clicked, open in a new browser window..

  • Return to the unfiltered view of the Document by clicking

See also: Searching Work Items.

Comments and Threads

Polarion LiveDoc Documents support comments in the body text, including the text of Work Items. If you have used the comments feature of Microsoft Office Word, you will find that comments in Documents work in much the same way. Comments may be added to Documents either online in the portal, or in document files that have been exported for comment/collaboration and then re-imported via the Word Round-trip feature.

Note that Document comments are not the same thing as the standard Work Item data field Comments. Document comments are only visible in the Document Editor, while Work Item comments are only visible in the Table and other tracker views of a Document's Work Items. Document comments are not exported or imported during Excel round-trip.

In order to add comments and replies, or resolve comments, you must be assigned a role that grants these permissions.

Please refer to the following figure as necessary when reading subsequent sections:

Figure 15.26. Documents Comments

Documents Comments

Accessing the Comments panel in the Sidebar, and in the Document body

Adding New Comments

To add new comments to an open Document:

  1. Place the insertion point (caret) in the position in the Document text where you want to insert a comment.

  2. Click the Add Comment button on the Document Editor toolbar. The sidebar displays the Comments panel, and a new comment is added ready for editing.

  3. Type the text of the comment and click the Save button on the Document toolbar when finished. A comment icon appears in the Document text at the insertion point.

Required Work Item Comments

As previously mentioned, only Document comments are accessible in the Document Editor. However, it is possible for Administrators to configure projects to make standard Comments field of Work Items a required field. When so configured, Work Items changes that affect the workflow cannot be saved without adding a comment to the Comments field. This will prevent Document users from saving the Document if they change a field such as Status in Work Item Properties, because the Comments field is not accessible in the Document Editor.

Hopefully you will be informed about required Work Item comments. If not, and you are prompted to add a Work Item comment after changing Status in one or more of the Document's Work Item(s), it means you cannot change Status in the Document Editor. You will instead need to use the Table view of the Document (accessible from the Document Editor toolbar).

In this situation, if you have unsaved content changes, go back to all Work Items in which you have changed Status, and set the value back to what it was before you changed it. This should enable you to save the content changes. If you have no pending content changes, you just can switch to the Table view immediately and opt to cancel changes when prompted.

In the Table view, browse or run a query to find the Work Item(s) for which you want to change Status. For each item, change the Status field as desired and add a new comment to the Comments.

Comments in Excel Round-trip

If Work Items containing Document comments are exported for Excel Round-trip, and the Work Item Description field is allowed by the exporting user to be editable in the exported Excel workbook, a placeholder {comment:id} is inserted into description text in the exported Excel workbook. This preserves the comment marker for the round-trip process and should not be removed from the exported Excel document.

Accessing Existing Comments

The Document body displays comment icons at every point where a comment has been inserted (see previous figure). Hover your pointer above any comment icon to see the comment text in a tool-tip. Click a comment icon to access the comment text in the sidebar Comments panel.

You can also access comments by browsing the Comments panel of the sidebar. Clicking on a comment in the sidebar scrolls the Document to the location of the selected comment in the text.

Replying to Existing Comments

You can use the comment reply feature to create threaded discussions inside a Document. To reply to an existing comment, select the comment in the sidebar Comments panel and click Reply. A new comment appears indented. Type your reply and click Save in the Document Editor toolbar.

Figure 15.27. Replies to a Comment

Replies to a Comment

Use replies to create threads of comments in Documents during collaboration.

Deleting Comments

If you decided that some comment is no longer needed, you can easily delete it. To delete a comment:

  1. Select the comment you want to delete in the Document or the sidebar Comments panel.

  2. In the sidebar, click the Delete in the selected comment.

TIP

If there are any replies to the comment you are deleting, all of them will be deleted also.

Resolving Document Comments and Threads

When stakeholders reach consensus through comments and comment threads, it can be useful to mark the comments and/or comment threads as Resolved. This hides them, after which individual users can opt to view them. It is also possible to reopen resolved comments if a stakeholder decides that further discussion is needed.

See also: Resolving Approval Comments, Resolving Work Item Comments and Threads.

To mark comments or threads as Resolved:

  1. Open the Comments panel of the Document sidebar (Show Sidebar on the Document Editor toolbar).

  2. Locate the comment to mark as resolved, hover your pointer over it, and click Resolve. In comment threads, you must mark the top-level comment.

To view resolved comments that are hidden (if any):

  1. Open the Comments panel of the Document sidebar.

  2. Click the (Pane Settings) icon in the header and choose Show Resolved Comments on the menu.

To reopen resolved comments or threads:

  1. Open the Comments panel of the Document sidebar.

  2. Show resolved comments as described above.

  3. Locate the resolved comment you want to reopen, hover over it and click Reopen.

TIP

Replying to any comment in a resolved thread reopens the entire thread.

See also: Signature Comments.

Images and Other Attachments

You can display images or attachment previews in a document. Simply place the cursor where you want the image or attachment preview to appear in the document an click the button. See here for details.

After inserting an image or attachment preview, you can add a Caption above or below it, or Resize it, or launch a full screen Preview of it.

Note

Your system or project administrator can optionally limit the file size of attachments. Contact your administrator if you are unable to upload an attachment due to such restriction.

Downloading an Attachment

To download an attachment:

  1. Open the Attachments panel of the Document Sidebar if it is not already open.

  2. Locate the attachment you want to update. Optionally use the search box at the top of the panel.

  3. Hover your pointer over the attachment you want to download and click the icon.

  4. If prompted by your browser, select the location on your local file system where you want to store the downloaded file, and confirm the save action. Otherwise, you can look for the downloaded file in the location where your browser stores downloads.

Updating an Attachment

To update an existing attachment:

  1. Open the Attachments panel of the Document Sidebar if it is not already open.

  2. Locate the attachment you want to update. Optionally use the search box at the top of the panel.

  3. Hover your pointer over the attachment you want to update and click the (Update) icon.

  4. Locate the updated version of the attachment file in your local file system, select it, and confirm your selection in your file selection dialog.

    NOTE: The file you upload should have the same filename and extension as the existing attachment. If you upload a different extension, you are asked if you wish to overwrite the existing attachment.

  5. After the selected file uploads, save the Document to complete the attachment update.

Deleting an Attachment

To delete an existing attachment:

  1. Open the Attachments panel of the Document Sidebar if it is not already open.

  2. Locate the attachment you want to delete. Optionally use the search box at the top of the panel.

  3. Hover your pointer over the attachment you want to delete and click the (Delete) icon .

  4. Save the Document to complete the delete operation.

    TIP: If you delete the wrong attachment by mistake, you can click Undo on the Document Editor toolbar, provided you did not yet save the Document. If you did save it, you can revert the Document to the previous revision in the History.

See also: User Reference: Documents: Document Sidebar: Attachments Panel.

Querying for Attachments

You can easily search Work Items to find all that have some kind of attachment. You can refine the search to include only items with attachments of specified file type(s), and also filter selected attachments according to:

  • Title

  • File name

  • Author

  • File size

  • Date modified

  • Content (provided that indexing of attachment content is enabled in the system configuration - see Administrator's Guide topic Advanced System Tuning).

To query for attachments in the Table view of Work Items, click the icon in the Query Builder, select one of the query elements beginning with the word "Attachment", and select appropriate criteria for the element. Add additional Attachment elements to further refine the query. For more information on queries, see the User Guide topic Searching Work Items.

Insert a Cross-reference

Cross-references let you link to Headings or Work Items within a document.

When clicked, they will scroll right to their target.

To distinguish them from Live Links, cross-references are underlined with a dashed grey line.

(They are underlined with a solid black line in exported PDFs.)

Note:

Unlike Live Links, cross-references are only navigational links and do not reflect an item's Status or Severity.

The Copy Cross-reference option is only visible for saved items.

  1. Scroll to the Heading or Work Item that you'd like to reference.

  2. Click on the Heading or Work Item's icon in the left margin.

  3. Hover over Copy, and click Cross-reference.

    Always use the method above to copy cross-references. (If you copy them any other way, they may not work as expected.)

  4. Press Ctrl+C when the Copy to Clipboard dialog appears.

  5. Scroll to, and click on where you'd like to place the cross-reference.

  6. Press Ctrl+V.

    (A cross-reference can be added to the document's body text or to the fields of a Work Item contained within the document.)

  7. If the document has outline numbering ON in the Document Properties sidebar, then the default link text will include them and the section's title in the link.

    (A reference's outline numbers are updated automatically whenever its source's numbers are changed.)

  8. Click to stick with the default outline numbers and title, or tick the options to omit the title or replace the outline numbers with the Project ID.

    (Click Custom Label… to define your own cross-reference link text.)

  9. The cross-reference appears in the selected position.

Note:

  • If a referenced Work Item or Heading is removed, any cross-references pointing to it will change to "Missing cross-reference".

    (It will also contain the missing item's ID, so that it can be easily tracked down.)

  • If the referenced item is filtered out of the document, then the cross-reference link will remain but won't scroll when clicked.

  • For an accurate cross-reference history view it in the Document's History.

  • When comparing different documents, cross-references will be highlighted as changed because they contain different URLs.

When Exporting Cross-references:

Exporting Cross-references to Microsoft Word:
  • A Cross-reference created in Polarion will survive a Word Round-trip, but instead of scrolling in the Word document, it will open the referenced object in Polarion.

  • Cross-references created in Word WILL NOT be recognized when imported into Polarion.

Exporting Cross-references to PDF:

Note:

Please use Adobe Acrobat Reader to view PDF documents.

  • If a cross-referenced item exists within the same PDF, then clicking its cross-reference will scroll right to it.

  • If a cross-referenced item is NOT within the PDF, then clicking its cross-reference will open the item in Document view in Polarion.

  • If a document was filtered before it was exported, cross-references for filtered items will be exported as plain text.

    (They will not scroll to, or open the items in Polarion when clicked.)

  • Cross-reference links are underlined with a solid black line in exported PDFs.

The Difference between a Live Link and a Cross-reference:

  • A Cross-reference will scroll to a Heading or Work Item within a Document.

  • When a Live Link is created, then clicked (Heading or Work Item icon Copy Link), it will open the linked item in the Work Item Viewer.

  • Live Links display the linked item's Status or Severity . (Cross-references do not.)

  • Cross-reference links can contain outline numbers. Live Links cannot.

Cross-references in Branched, Variant or Reused Documents:

Things to know about cross-references and Branched, Variant or Reused Documents:

  • If a cross-reference points to a section within a master Document, it will point to its matching counterpart section in Branched, Variant or Reused versions.

  • If a referenced Work Item that's targeted in a cross-reference is overwritten, the cross-reference will be updated so that it still scrolls to the same position.

  • When a Work Item is opened in the Work Item form, any cross-reference contained within it will link to the master document.

  • If you change the title of a cross-referenced Heading or Work item, the cross-reference link text will update accordingly.

    (But only within the document version that the Heading was changed in.)

Note:

Currently cross-references between Documents, Revisions and Baselines is not fully supported and cannot be rendered as Live Links.

You can repair missing cross-references by inserting the missing item using the Insert Live/Frozen reference merge action.

Inserting a Diagram

Polarion provides the Diagram Editor tool for creating and editing diagrams. You can use it to create and edit diagrams in Documents, including Work Items contained in Documents. You can also use it to create diagrams in the Description field of Work Items you edit in the Work Item Tracker.

For information on using this feature, please see the User Reference topic Diagram Editor.

Inserting a Table of Contents

You can insert a table of contents (TOC) into a Document. The content of the TOC is based on the headings in the Document. If you insert a TOC into a Document that has no headings, the message No table of contents entries found appears at the point you insert the TOC. The TOC is automatically updated when you add new headings and save the Document. TOC items are links which scroll the page to the respective heading. You can explicitly update or delete the Document's TOC any time, and you can insert a new paragraph before or after the TOC.

The Document Editor allows up to 29 heading levels. However, the TOC displays only up to 5 heading levels.

To insert a Table of Contents:

  1. Place the insertion point (caret) at the position in the Document where you want to insert the TOC.

  2. In the Document editor toolbar, click the Insert drop-down (see figure below) and choose Table of Contents. The TOC is inserted and the (Table of Contents) icon appears outside the Document border.

    Figure 15.28. Document Insert Menu

    Document Insert Menu

    Toolbar icon inserts several types of content into Documents

Updating the TOC

The Document TOC is updated automatically when you save the Document. However, you can explicitly update it while editing the Document. Note that you cannot manually edit any text in the Table of Contents.

To update the Table of Contents:

  1. Click on the TOC icon on the Document background. The TOC actions menu appears.

  2. Choose Update on the TOC actions menu.

Deleting the TOC

To delete the TOC from the Document:

  1. Click on the TOC icon on the Document background. The TOC actions menu appears.

  2. Choose Delete on the TOC actions menu. The TOC is no longer visible in the Document.

  3. Save the Document to complete the deletion of the TOC.

Inserting New Paragraphs

You can insert a new paragraph before or after the Table of Contents in a Document.

To insert a new paragraph:

  1. Click on the TOC icon on the Document background. The TOC actions menu appears.

  2. On the TOC actions menu choose Insert > Paragraph Above or Insert > Paragraph Below.

Inserting a Table of Figures

To insert a Table of Figures in a Document, click the Insert drop-down, select Table of Figures on the menu, and in the dialog choose the select Figures option. The table will include links to images and/or diagrams in the Document that have a caption with the caption label "Figure". For more information, see the User Reference topic Captions.

Note

The Table of Figures appears only in documents created by export to PDF and Round-trip for Microsoft Word. A placeholder appears in your Polarion Document.

Inserting a Table of Tables

To insert a Table of Tables in a Document, click the Insert drop-down, select Table of Figures on the menu, and in the dialog choose the select Table option. The table will include links to tables in the Document that have a caption with the caption label "Table". For more information, see the User Reference topic Captions.

Note

The Table of Tables appears only in documents generated by export to PDF and Round-trip for Microsoft Word. A placeholder appears in your Polarion Document.

Inserting Page Breaks

You can insert explicit page breaks in a Document. Such breaks will occur in exported documents after export to PDF and Microsoft Word (Round-trip).

To insert a page break:

  1. Place the insertion point at the end of the line where you want to insert a page break, or on an empty line.

  2. In the Document editor toolbar, click the insert drop-down (see figure at Creating a Table of Contents) and choose Page Break. The icon (Page Break) icon appears outside the Document border on the line where the page break will occur.

To remove a page break, click the Page Break icon and choose Delete.

Inserting Classic Wiki Macros and Content

It is possible to insert textual content formatted with Classic Wiki syntax, or Classic Wiki macros which render content dynamically. For example, you might create a Document that reports the current status of Work Items in the project using the {workitems} macro with a query parameter to display some subset of Work Items in the Document... all currently open items, items closed for some time point, etc.

Figure 15.29. Classic Wiki Content in a Document

Classic Wiki Content in a Document

Classic Wiki macros can help you display useful information in Documents

To enter Classic Wiki content into a Document:

  1. Open the Document for editing.

  2. In the Document editor toolbar, click the insert drop-down (see figure below) and choose Wiki Content. The Insert or Modify Wiki Content dialog appears.

  3. Enter the desired Classic Wiki macro or other content with Classic Wiki mark-up into the edit field in the dialog, and click OK when finished.

  4. Save the Document.

For general information on using the Classic Wiki, including editing of Classic Wiki pages, see User Guide:  Appendix: Using Classic Wiki. For information on Wiki macros, see User Guide: Appendix: Using Classic Wiki: Adding Dynamic Content in Wiki Pages.

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

Modifying Wiki Content

You can modify existing embedded wiki content. For example, you might modify the query of an existing workitems macro to retrieve a different set of Work Items, or display more or fewer Work Item fields.

To modify existing Wiki content in an open Document:

  1. After locating the content you want to modify, click on the Wiki Content icon to the left of the Document border.

  2. On the menu, click Modify to display the Wiki Content dialog.

  3. Change the content and desired and click OK.

Deleting Embedded Wiki Content

After locating the content you want to modify, click on the Wiki Content icon to the left of the Document border, and then choose the Delete item on the menu.

Resolving Conflicts

If you and another user edit the same Document at the same time, it is possible that your changes can conflict with changes made by another user.

Polarion attempts to merge concurrent changes to Documents and does so silently when it is clear that it is safe. In cases where there is some question, a dialog is presented to the user saving potentially conflicting changes. The dialog summarizes the issues, provides some explanatory Help text, and provides links that open separate browser tabs or windows in which the user can review his potentially conflicting changes and changes of other users. The user can then make an informed decision about saving the pending changes. For information on how Polarion handles different merge scenarios, see the User Reference topic Merging of Concurrent Changes.

During editing, an item Compare with > Unsaved Changes appears on the Actions Menu of the Document Editor toolbar. This action leads to a page (in a new browser instance/tab) where you can compare the current state of the Document in the repository and your unsaved changes.