Document Actions

This section describes various actions users may sometimes need to perform with Documents:

Important

If a reused Document contains Work Items that have been approved using an electronic signature the Work Items in new Documents will not show any indication of the source item's signature, and reused items in the new Document are not approved or electronically signed. These items must also be reviewed, approved, and e-signed.

Reusing a Document

You can reuse an existing Document, or any revision of an existing Document. To determine the number of a revision of a Document to reuse, check the Document history. You can reuse Documents in the same project, in the same space or a different space, or in a different project in any space in that project. You can either create a new, stand-alone copy of a reused Document, or a "derived" copy in which the text/image content can only be modified from the base Document, but which allows changes to some Work Item fields in the copy - "status", for example.

You can reuse multiple Documents in a single operation, optionally keeping relative Work Item links between a group of Documents that are reused at once. For example, if you have a specification Document containing requirements and a Document containing a set of test cases that cover the functional requirements, you can reuse both the requirements Document and the Document with test cases and have test cases from the reused test case Document linked to the functional requirements in the reused requirement Document.

If your system or project is configured to support Document types, a reused Document will have the same type as the original. If your system is configured to use Document workflow, the workflow on new Documents created by reuse is set to the initial workflow status per the workflow configuration.

To reuse a Document:

  1. Open the project containing the Document you want to reuse.

  2. Open the Document you want to reuse in the Document Editor.

  3. On the Document toolbar, click on Actions Menu and choose Reuse. The Reuse Document dialog appears.

  4. If you want to reuse a revision of the Document other than the current head revision, click the button in next to the Revision label. In the Select Document Revision dialog, select the Revision option and enter the number of the Document revision you want to reuse.

  5. In the Title field, optionally specify a different title for the new Document that will result from the reuse operation.

    If you modify the Title field, and you want the Title styled heading in the Document updated to that value, check the box labeled Update Title (Heading) in the Document. Clear the box if you want the original title preserved in the Document's title heading.

  6. In the Name (ID) field, optionally specify a different name for the new Document that will result from the reuse operation. If this Document will be saved in the same space as the base Document, you must specify a new name so as not to conflict with the name of the base Document.

  7. By default, the new Document will be saved in the same project as the base Document. If you want to save it in a different project, select the target project in the Project list.

  8. By default, the new Document will be saved in the "Default" space of the project selected in Project. If you want to save it to a different space, select the space name in the Space list.

  9. Optionally check the Remove outgoing Work Item links box. When checked, links from Work Items contained in the base Document to other Work Items in the project (or another project) are not created in the duplicated Work Items in the new Document. You might want to do this if the base Document is some kind of working or production Document, as opposed to some kind of "library" Document.

  10. Select a reuse option.

    To create a new, stand-alone, fully editable copy of the base Document, select Create a new stand-alone copy of the Document.

    If you select this option, also specify whether or not to link the duplicate Document's Work Items to the base Document's Work Items. If you opt to link, select the link role in the drop-down list.

    To create a copy of the base Document which cannot be edited (except for some Work Item field values), select Create a new derived Document. (For more information, see  Derived Documents later in this section.)

    If you select this option, specify which Work Item fields should be read-only in the derived duplicate. By default, the title and description fields are specified. You may optionally add other fields, delimiting the list with a comma. For example, if you want the severity file to be read only in the derived Document, add it to the Derived Fields field.

  11. Click OK to create the new Document copy in the specified project and space. The new copy opens in the Document Editor and is selected in Navigation. If the new copy was saved to a different project from the base Document, that project is opened before opening the Document.

Derived Documents

Reusing a Document with the option to create a new "derived Document" enables you to use the first Document as a "standard". For example, if you have a standard set of requirements or specifications that must be implemented in every project, you can create one "base" Document, and reuse it in projects as a derived Document. The derived Document is an exact copy of the base Document which cannot be modified other than to set values of some Work Item fields... Status or Severity, for example (if these were not set read-only when the base Document was reused). Work Items contained in the base Document are duplicated in the project containing the derived Document with new IDs. These items can then be tracked and managed as project Work Items (i.e. the items are not part of the project containing the base Document).

The advantage of derived Documents is that if something changes in the base Document... a new requirement is added, for example... the change can be easily propagated to all derived Documents, resulting in the creation new, open Work Items and notifications to the Document owner.

There are several important things to keep in mind about derived Documents:

  • The derived Document is linked to the source Document.

  • Work Items in the derived Document are linked to the same Work Items in the source Document with the "is derived from" link role.

  • If the source Document is changed, you can update a derived Document to reflect the changes.

  • If the source Document is moved or renamed, links to all derived Documents are updated automatically.

  • If you try to remove the source Document (or the space containing it which also removes the source Document), you are warned about the presence of derived Documents and offered the choice of canceling the action, or converting the documents to non-derived, stand-alone Documents thereby losing the link to the source Document and the possibility to update the derived Document from it. (Links between any contained Work Items are preserved.)

  • If the project is configured to support Document Types and Document Workflow, updating a derived Document from the Master does not affect the type or status of the derived Document.

Updating Derived Documents

When the content of a base Document changes, the change may be optionally propagated to any or all derived Documents. Changes are NOT propagated automatically in order that users have the option not to propagate base Document changes to some project(s) or Document(s). The owner of the base Document should manually notify owners of derived Documents to perform the update.

To update a derived Document with changes from its base Document:

  1. Open the derived Document in the Document Editor.

  2. On the Document Editor tool bar, click on Actions Menu and choose Update Document.

TIP

You can also update the derived Document using the Update link in the Document Properties panel of the Document Sidebar.

Referenced Work Items in a Copy

If you copy a Document that contains referenced Work Items, then the referenced items will be copied as referenced Work Items. If any of these items are frozen to a specific revision of the original Document, they will remain frozen to that same revision in the new Document. Referenced Work Items show the (Revision) icon. The icon tooltip displays the revision number.

Marking Links As Suspect

When updating a derived Document, there is an option to set the Suspect attribute on incoming links. When checked, then links incoming to Work Items modified by the update operation are marked as suspect. Note that the user updating the derived Document and setting the Suspect option must have permissions to update the linked items, otherwise the update will not proceed and the user receives a message.

For example, setting links as Suspect would be desirable when updating a derived requirements specification Document which has verifying test cases linked to contained requirements. Because the linked test cases could be invalidated or broken by the update, having the links Suspected helps ensure that owners of the test cases are made aware that changes have occurred in the requirements so they can review the test cases to ensure validity.

Reusing Multiple Documents

It is possible to reuse multiple Documents in a single operation. This can be especially useful where you have a set of "standard" Documents which need to be reused in multiple projects. The base Documents to be reused can reside in any project and space, and may be reused in any project/space.

To reuse multiple Document in a single operation:

  1. In Navigation in the project containing the base Documents to be reused, navigate to the space containing the base Documents and select Index. The Index page opens listing all Documents in the space.

  2. Check the box on the row of each Document you want to reuse, and then on the toolbar, click the Reuse Documents button. The Reuse Documents wizard appears.

  3. On the Selection page, set the check box options as desired.

    Next, select any additional Documents you want to reuse. Initially the table of selected Documents contains only the one(s) you selected on the Index page, which means they are from the current project and space. You can add Documents from any project, and from any space in a specified project. Use the icon to add a new row for each Document you want to reuse, specifying the project, space in the selected project, and Document in the selected space. If you make a mistake, use the to remove the incorrect Document's row in the table. By default the Head revision each selected Document in the table will be the revision reused. If you want to reuse a different revision of any Document, click Head on the relevant table row and specify the number of the revision you want to reuse.

    Click Next to move to the next page of the Wizard. The next steps depend on whether or not you checked the option Use same project and settings for all reused Documents (it is checked by default).

If you checked Use same project and settings for all reused Documents:

  1. In the Project list, select the project in which the selected Document(s) should be reused. (The current project is the default.) A new copy of each document selected for reuse will be created in the specified project.

  2. Provide a name and title for each Document, and specify the space in the target project where each reused Document should be created. Note that each Document's name is the identifier (ID) for the system, and therefore must be unique within the target space.

  3. Select the desired reuse option (stand-alone copy, or derived Document) and specify the options for your selection. Click Next when finished.

If you did NOT check Use same project and settings for all reused Documents:

In the Following Steps pane of the Wizard, you will see a Settings item for each of the base Documents you selected for reuse. So for example, if you are reusing 3 Documents, you will see Settings 1/3 Settings 2/3 Settings 3/3. These are settings pages for each of the Base documents on which you can specify different reuse options for each of the Documents.

On the Settings page for each base Document:

  1. Specify in which project the Document should be reused. (The current project is the default.) A new copy of the Document will be created in the specified project.

  2. Provide a name and title for the Document, and specify the space in the target project where the reused Document should be created. Note that each Document's name is the identifier (ID) for the system, and therefore must be unique within the target space.

  3. Select the desired reuse option (stand-alone copy, or derived Document) and specify the options for your selection.

  4. Click Next when finished with the base Document settings page.

After completing the reuse settings for all base Documents, the Execution page of the wizard appears, and copies of the base Documents are created according to the settings. When all copies have been created and stored, the Execution page displays a button for each of the new Documents enabling you to open any or all in the Document Editor. Documents open in a new browser instance. When you have opened the Documents you want, click Finish to close the wizard window.

Branching Documents

Polarion supports branching of entire Documents, or branching of existing Document-based Work Items into a new Document, in both cases creating a variant Document. As an illustrative use case, consider a scenario where there is an existing requirements specification for some application... a game, for example. The original specification is for the game running on desktop computers. Now there is a decision to create variants of the game for several popular mobile platforms and devices.

Much of the original specification is applicable to all the variants... rules of the game, for example. However, the user interactions will be different for each mobile platform, so you need some way to specify platform-specific requirements while keeping those that a applicable to all platforms However, the scenario doesn't end there. Some of the user interactions will be the same across all devices running Mobile Platform A, but there will be additional requirements for one or more specific supported devices running Platform A.

Figure 15.34. Document Live Branch

Document Live Branch

Branching Documents and Work Items

In this scenario, the requirements specification Document for desktop platforms is branched to create variant specifications for 2 supported mobile platforms... Platform A and Platform B. In each of the branched variants, some requirements from the original or "master" are "referenced". That is, they appear in the variant, but are not contained in it, and may not be modified in it. In the Platform B specification, one requirement from the master is removed from the variant and replaced by a new platform-specific requirement. Then new "native" Work Items (user stories because the mobile development uses Scrum workflow) are added to the branched specification Documents to address requirements specific to each platform.

At this stage the specification Documents are: Desktop Requirements Specification (master Document), Mobile Platform A Requirements Specification, and Mobile Platform B Requirements Specification. If Work Items in the master Document are modified, the changes propagate to the variant Documents. In cases where this is not wanted, or is not wanted until some future time, the variant Documents can be "frozen" to a specific Revision of the master Document. Subsequent revisions of the master's Work Items will not propagate to frozen variants until such time as the variants are "unfrozen". Then, the branch will be "live" and all subsequent modification of the master Document's Work Items will propagate to variants.

Now, the device variants on Platform A need to be addressed. The new native requirements from the Platform A specification are valid for Device 1, but there are some additional ones required to support the device. The approach here is to create a new Document, and then copy all applicable content from Mobile Platform A Requirements Specification and paste it into it. Any headings and plain text are copied verbatim and changes in the Platform A are not propagated. Copied and pasted Work Items ("referenced" Work Items) appear in the Device 1 specification Document, but are not contained in it. Referenced Work Items can only be modified in the Document in which they are "native"... in this case the Platform A specification.

If the project of the original Document(s) is configured to support Document Types and Document Workflow:

  • The Document Type of any branched Document will be the same as that of the original Document from which it was branched.

  • Every branched Document will have its workflow reset. Its Status will be set to the configured initial Status, and the initial workflow action will be executed.

Variants Based on a Revision

There may be situations when a variant needs to be based on a specific historical revision (not depicted in the previous figure). For example, suppose requirements for Device 2 need to be based on the Platform A specification as it was at the time of Release 4. Assuming the a Baseline was created at the time of this release, you could open the Baseline, browse to the Platform A specification, copy content from the baseline Document, and paste into the variant Document (opened in another browser instance). Alternatively, you could open the baseline revision of the Document in History and use the Branch Document feature in the Document Editor.

In the variant Document (Device 1), any of the referenced Work Items can be frozen to a specific revision of the Work Item. If the items are subsequently updated in the source Document (Platform A specification), the changes will not propagate to the branched Work Items in the variant Document until such time as the Work Items in the variant are explicitly unfrozen by a user. Freezing referenced Work Items to a revision would generally not be needed when the source of the items is a historical revision of a Document, because the source Document revision cannot be modified.

Creating a Branched Document

In order to branch a Document, you must have permissions for creating new Documents and new Work Items in the project where the branched Document will be created. You can branch the current state of the Document, or the state from a Baseline or other historical revision of the Document.

Branching the Current State

This section describes how to branch the current state of a Document (i.e. the "Head" revision in the repository).

To create a new branched Document:

  1. Locate the Document you want to branch and open it for editing.

  2. On the toolbar of the Document Editor, click the Actions Menu icon and choose Branch in the drop-down menu. The Branch Document dialog opens.

  3. Set the dialog fields as follows:

    • Title: Optionally specify a new title for the branched Document.

      If you want to branch a revision other then the current one, click the button (labeled "HEAD" or with the number of the revision you are branching) and select the revision from which to branch a new Document.

    • If you have modified the Title field, and you want the Title styled heading in the Document updated to that value, check the box labeled Update Title (Heading) in the Document. Clear the box if you want the original title preserved in the Document's title heading.

    • Name (ID): If you want to create the branched Document in the same space as the Document you are branching, you must enter a new name/ID. The new value must be unique within the space.

    • Project: If you want to create the branched Document in a different project, select the target project in the drop-down list. The default value is the name of the current project.

    • Space: If you want to create the branched Document in a different space than the one selected in this field, select the target space in the drop-down list. The list contains the names of spaced in the project selected in the Project field.

  4. Click OK to create a new branched Document in the specified project and space.

Branching a Historical Revision

To branch a historical revision:

  1. Open the Document to be branched and click the History icon to open the Document's history.

  2. Locate the revision you want to branch and click Show in the Actions column to open the revision.

  3. On the Document Editor toolbar, click the Actions Menu button and choose Branch.

  4. Set the dialog fields as described in the previous section Branching the Current State.

Branching a Baseline

The procedure is similar to that described in the previous section on branching a historical revision.

  1. Open the Baseline in which is captured the state of the Document from which you want to create a branched Document.

  2. Click the History button on the Document Editor toolbar to open the Document history.

  3. Locate the revision of the Baseline you are now working. Baseline revisions have a light green background in revisions table, and the Revision # column contains the name of the Baseline as well as the revision number.

    In the row of the Baseline revision, click Show in the Actions column to open the revision.

  4. On the Document Editor toolbar, click the Actions Menu button, choose Branch, and proceed as previously described.

Branching a Filtered Document

You might want to create a branched Document that references only a subset of the Work Items in the master. For example, you might create a branched Document containing only items having severity "Must Have" and status "Accepted".

To create such a branched Document, you must first filter the master document so that it shows only the Work Items you want referenced in the branched Document. With the master Document open in the editor, click the Actions Menu button and choose Filter. Enter a query that filters the Document's Work Items. For example, status:accepted AND severity:must_have.

When the Document is filtered as you want it, proceed to branch it the same way as an unfiltered Document.

Working with Branched Documents

Once you have some branched Documents, there are various things you may need to do with them. This section describes a number of commonly needed features and operations:

Accessing and Reading Branched Documents

You access and open branched Documents just like any other Document. You can browse spaces in Navigation, browse the Index page of any space, or search for the Document.

You can tell if the Document you are reading is a branched one, and from which Document it was branched in the Document Properties panel of the Document Sidebar. The name of the master Document is shown, and the name is a hyperlink that opens the master.

Comparing Documents

You can easily compare any two Documents. A common use case is comparing a branched Document with the original or "master" Document. You can compare the full content, Work Items, or Work Item fields in different compare views.

To compare Documents:

  1. Open a Document that you want to compare with another in the Document Editor. If you want to compare a branched Document to the master, open the branched Document.

  2. On the toolbar, click the (Actions) icon. If comparing a branched Document to its master, choose Compare with > Master Document. To compare any open Document to any other Document, choose Compare with > Other Document.

In every case, you can compare the opened Document to either the current revision of the other Document (HEAD), or an earlier revision. The HEAD revision is the default. To select a different revision, click the HEAD button and use the Revision Picker dialog to select the desired revision of the Document you want to compare to.

Selecting a Compare View

There are 3 compare views that compare different content of the two Documents. Change the view by clicking the respective buttons on the compare page toolbar.

  • Document: displays a comparison of the text content of the Documents, including the text of headings and Work Items. This view is opened by default when you compare Documents.

  • Work Items: displays a comparison of the Documents' Work Items and their structure. The Merge side bar is available enabling you to merge Work Items and/or fields between the compared Documents. (For more information, see the User Guide topic Merging Document Work Items.)

    Note that some fields are not displayed in the Work Items compare view even if there have been changes to those fields:

    • Author

    • Comments

    • Created

    • Module

  • Fields: displays a comparison of the Document's fields. For example, Title, Name, Branched From, etc.

Comparing to a Filtered Document

The topic Branching a Filtered Document describes how a Document may be branched from a filtered state, so that the branched Document only references the Work Items shown by the filter. If you want to compare the branched Document to the master, you need to specify the same filter query in the Filter field of the Compare Document dialog.

In the previous example of filtering the master Document before branching so that it shows only items with status "Accepted" and severity "Must Have", the filter query was status:accepted AND severity:must_have. In order to compare the branched Document with only the same Work Items in the master, you would use this same query string in the Filter field of the dialog.

Exporting Comparison to PDF

You can export the Document comparison to PDF using the Export to PDF item on the Operation menu in the comparison results page. Only the Document comparison view can be exported, not the Work Items comparison view.

An administrator can optionally configure a header/footer for exporting the comparison view. See the Administrator's Reference topic PDF Export Header/Footer Properties.

Comparing to Last Saved Version

On the Document Editor toolbar, the operation Compare With > Last Saved Version is available. This compares the current state of the Document with the version that you opened in the Document Editor, or to the last saved version if the Document was saved after that.

Finding Documents Referencing Work Items

It is possible to have several (even many) Documents that reference a Work Item. For example, there might be a core set of requirements for a product that has 25 different models. There might be 25 branched Documents each containing the specifications for one model, and each Document referencing the core requirements. Suppose you are looking at one specific referenced requirement and you want to know what other Documents reference it.

To find all referencing Documents for a Work Item:

  1. If you are looking at the referenced Work Item in a branched Document, open it in the Tracker. Click the type icon by the left border and choose Open Item on the menu.

  2. On referenced Work Item's tracker page, the Open in Document button on the toolbar displays an arrow symbol. Click the arrow to see a menu listing all the Documents that reference the Work Item.

    You can choose any item in the list to open the referencing Document.

Work Items in Branched Documents

This section covers several features and other information that pertain specifically to Work Items in a branched Document. As previously mentioned, when you create a branched Document, the Work Items you see visually are not actually contained in the Document, but rather are "referenced" from the master Document. This is visually rendered in the Document Editor by means of a dotted gray left border on the Work Items. Referenced Work Items cannot be edited in the branched Document. If referenced Work Items are exported for Word or Excel round-trip from a branched Document, they cannot be edited in the exported Word or Excel file.

Commenting Referenced Work Items

You can comment referenced Work Items in a branched Document in the same way you add comments to regular Documents (including users of Polarion Reviewer ).

With an appropriate product license, referenced Work Items in a branched Document can be commented externally via round-trip for Microsoft Word or Microsoft Excel.

Branching Work Items with "Overwrite"

In a branched Document, you can branch referenced Work Items to create a Document-local copy of the items using "Overwrite". Branched Work Items are contained in the branched Document and no longer referenced from the master Document. Rather, the local copy of each item is linked to the original item in the master Document so that traceability is maintained. If the original item subsequently changes in the master Document, the change does not propagate to the copy in the branched Document. Likewise, changes to the branched Work Item have no effect on the original.

When branching a referenced Work Item, you can create the branched Document-local copy either from the current (Head) revision of the item, or from any revision of the item in its History.

When overwriting, the modified Work Item uses the original Work Item as a template, but does not copy the values of workflow fields like those listed below:

  • Approvals

  • Author

  • Created

  • Comments

  • Work Records

  • Time Spent

  • Remaining Estimate

  • Status

  • Linked Revisions

The fields above can be modified before the newly created Work Item is saved.

(Except "Author" and "Created". They are populated with the user that did the overwrite and the time and date it was done.)

Overwrite a single referenced Work Item in a branched Document:

  1. Open the branched document containing the referenced Work Item to overwrite.

  2. Highlight a single referenced Work Item.

  3. Click on the Work Item Icon on the left and then “Overwrite” in the menu that appears

  4. The dotted line of the referenced Work Item becomes a solid line and available fields are editable in the Work Item Properties sidebar.

    ( then Work Item Properties to launch the Work Items Properties sidebar.)

  5. Edit the desired Work Item fields and click Save.

Bulk Overwrite multiple referenced Work Items in a branched Document:

(NOTE: The maximum number of Work Items that can be overwritten at one time is 200.)

  1. Open the branched document containing the referenced Work Items to overwrite.

  2. Highlight the multiple referenced Work Items to overwrite.

  3. Open the Work Items Properties sidebar.

    ( then Work Item Properties)

  4. Click on the button in the sidebar.

  5. Edit the desired Work Item fields and click Save.

TIP

If you want to branch a specific revision of a referenced Work Item, you must first freeze it at the revision you want to branch (see next section) and then perform the above steps on the item.

Overwriting a Referenced Work Item with Restrictions

When overwriting a Work Item in a generated Variant specification document, the restriction editor loads the Feature Model from the master project. (The Master Specification the Variant specification branch was generated from). This allows you to merge the overwritten Work Item back into the Master Specification without losing the restriction definition.

Freezing Work Items at a Revision

You may decide you want to prevent updating of one or more referenced Work Items in a branched Document if the items change in the master Document. In that case, you can "freeze" any referenced Work Item to a specific revision (of the Work Item, not the Document). The situation may be temporary: while the master Document is still in progress, for example. When a Work Item is frozen, a small clock icon appears with its title in the Work Item Properties pane of the Document Sidebar.

You can "unfreeze" any referenced Work Item previously frozen to a revision. Unfreezing will cause any changes that occurred in the master Work Item to propagate to, and appear in the branched Document. During development of the master Document, you may freeze previously frozen Work Items at a different revisions throughout the process. Any changes in the new revision will propagate to the referenced item in the branched Document, but any changes subsequent to that revision will not propagate until you either unfreeze the item, or freeze it at a different (probably later) revision. You can perform the freeze, unfreeze, and revision change operations on multiple referenced Work Items at once.

Note that freeze, unfreeze, and revision change operations affect only the branched Document in which they are performed. Other branched Documents referencing the same Work Items are not affected. For example, suppose Work Item WI-5 is referenced in two branched Documents: BD1 and BD2. The owner of BD1 opens it and freezes WI-5 at Revision 152 (the current Head revision). Later, WI-5 is changed in the master Document. The change is not reflected in BD1 because WI-5 is frozen. It is reflected in BD2 because freezing the item in BD1 only affects that Document.

To freeze a single referenced Work Item at a revision:

  1. With the branched Document open in the Document Editor, click anywhere on the content of the Work Item you want to freeze.

  2. Click the type icon at the left border and click Freeze on the drop-down menu. The Freeze Work Item dialog opens.

  3. In the Freeze at Revision field, enter the revision number at which you want to freeze this Work Item. You can click the Select Revision icon and use the Revision Picker dialog to select a revision number.

    Click OK to complete the freeze operation.

  4. After closing the dialog, save the Document. You can confirm that the item is frozen at the revision you specified by opening the Document Sidebar (if hidden) and then opening the Work Item Properties pane. A small click icon appears by the title, and the icon tool-tip will indicate the revision number.

To unfreeze a previously frozen Work Item, or change the revision at which it is frozen:

  1. Select the Work Item in the branched Document.

  2. Click the type icon at the left border and click Freeze/Unfreeze on the drop-down menu. The Freeze/Unfreeze Work Item dialog opens.

  3. If you want to unfreeze the item, select the Unfreeze option and click OK.

    If you want to freeze the item at a different revision, select the Freeze at Revision option and enter the desired revision number, or use the Revision Picker dialog to select it. Click OK to finish.

  4. After closing the dialog, save the Document to apply the changes.

To freeze/unfreeze, or change the revision of multiple referenced Work Items at once:

  1. In the branched Document, select the Work Items you want to freeze or unfreeze.

  2. Open the Document Sidebar and its Work Item Properties panel.

  3. Click the Freeze/Unfreeze button.

  4. In the dialog, select the option you want to perform on all the selected referenced Work Items.

    Note that if the selection contains Document-native (i.e. unreferenced) Work Items, the operation ignore them and process only referenced items.

  5. After closing the dialog, save the Document to apply the changes.

Inserting Referenced Work Items in Bulk

It is possible to insert multiple referenced Work Items into a Document in a single operation. Work Items can be selected in the Tracker in the same way as selection for Bulk Edit, and the references copied and inserted into a Document.

To insert multiple referenced Work Items:

  1. Open the target Document in the Document Editor, and open the Work Items topic (i.e. the Tracker) in a separate browser tab.

  2. In the Tracker, construct and run a query, if necessary, so that all the desired Work Items appear in the query results in the top half of the page.

  3. In the table in the top half of the page, select all the Work Items you want to have referenced in your Document.

  4. In the toolbar lower half of the page, click (Actions) and select Copy Link and in the dialog, copy all selected links to your clipboard. You can optionally select Copy IDs. The end result is the same.

  5. Go to your Document and place the insertion point on an empty line where you want to insert the referenced items.

  6. On the toolbar, click the drop-down icon beside the Work Item type icon (tooltip: "Mark/Unmark Text as...) and on the drop-down menu select Insert Referenced Work Items.

  7. In the Insert Referenced Work Items dialog, paste the links (or IDs) from your clipboard into the first text field, then click OK button.

Tracing to Linked Work Items

When you have referenced Work Items in a branched Document, you may want to find what other Work Items are linked to them. These linked items are of course external to the branched Document. This is easily accomplished using the Tree view:

  1. Open a branched Document in the Document Editor.

  2. On the Document toolbar, select the Tree view (see figure below).

    Figure 15.35. Document Editor Toolbar

    Document Editor Toolbar

    Select the Tree view

The Tree view shows a hierarchical view of the Document's structure including both referenced Work Items, and items contained in the Document. The toolbar provides a special set of controls enabling you to show linked or backlinked Work Items having a specified link role. You can control the depth of the search, optionally include linked commits (revisions), and optionally filter all levels of the Document tree using the current query. (If Filter Linked Items is not checked, the query is applied only to the first level of the tree.)

Referenced Work Item Outline Numbers

You can enable outline numbering in a branched Document in the same way you do for non-branched Documents. See User Guide topic Using Outline Numbering.

In a branched Document, the outline numbering you see pertains only to the structure of that Document regardless of any numbering that may be applied to referenced Work Items in the master Document. For example, suppose that right after you branch a Document, you have an outline sequence 1.1, 1.2, 1.3, and 1.4 in referenced items from the master Document, Now you insert a new Work Item in the branched Document between referenced item 1.2 and referenced item 1.3. Your new item will be numbered 1.3, the item that was numbered 1.4 will become numbered as 1.5, and the item that was 1.5 will be numbered as 1.6, and so on down the Document content.

Moving or Renaming a Document

Your can move a Live Document to a different Space or Subspace, either keeping the same name, or renaming it in the process, or you can rename a Document in the same space. You can only move Documents within the current project, and the target space must already exist in order to move a Document to it. That is, you cannot create a new space "on the fly" during the move operation.

To move or rename a Document:

  1. Open the project to which the Document belongs, if the project is not already open.

  2. In Navigation, expand Documents and Pages and browse to the Space or Subspace containing the document and select the Index within it.

    If you're not sure where the Document is, you can filter Navigation or use the Search feature to locate the Document and determine the space where it resides.

  3. In the Index page, locate the Document you want to move or rename and check the box on its row in the table.

  4. In the page toolbar, click the Move/Rename Document button. The Move or Rename Document dialog appears.

  5. To rename the selected Document in the current space, type a new name in the Name (ID) field, and optionally specify a new value in the Title field. The current space is selected by default in the Space field). The new name you choose must be unique within the current space. If you try to rename a Document with a name that already exists for a Document in the space, Polarion will display a message and you can try again.

    Document name is case sensitive. For example, you could rename a Document My Document as My document.

  6. To move the Document to a different Space or Subspace, select the space name in the Space list. If you also want the Document renamed, type a new name in the Name (ID) field (and optionally change Title). The name must be unique within the target space.

    The Space hierarchy, if you've already created one, will appear in the drop-down menu as follows:

  7. Click OK to complete the operation.

TIPS

Displaying of Document compare before and after moving may take a long time. The Document before renaming is not cached and the entire history is loaded from the repository.

The Rename action is also available in the Document Properties panel of the Document Sidebar.

Changing Work Item Type

A Document can be configured to contain multiple Work Item types (see Multiple Work Item Types), and types may be added to a Document any time. When multiple types are configured in the Work Item Presentation, then any Work Item type in the Document can be changed to any other configured type. For example, a Document might initially be configured to contain only Software Requirement type items. Later, it may be decided that the same Document should also contain System Requirement type items, and the Document configuration changed to include that type. Then, some existing Software Requirement items might be identified as actually being system requirements, and those items changed to the System Requirement type.

The change can be made either in the Document, or in the Work Item Editor (see figure below). Note that when changed to another type, a Work Item will display the fields and other properties that are configured for that type in the Work Item Presentation dialog.

Important

The Work Item Link Rules in the project configuration are not checked when a Work Item's type is changed. If the changed Work Item has linked Work Items, the links should be checked to ensure that the link roles are still valid for the item's new type. Also, if the item has custom fields, it is possible that some custom field values might be converted during type change, depending on the configuration of the target type.

Figure 15.36. Options for Changing Work Item Type

Options for Changing Work Item Type

Work Item type can be changed via the Document Editor or the Work Item Editor

Using the Document Editor

To change the type of a Work Item using the Document Editor:

  1. Click anywhere in the Work Item in the Document body to select it.

  2. On the Document Editor toolbar, click the drop-down control beside the Mark/Unmark Text button and select the desired type on the drop-down menu.

  3. Save the Document to complete the change.

Using the Work Item Editor

To change the type of a Work Item using the Work Item Editor:

  1. In the Document Editor, click the icon to the left of the desired Work Item and choose Open Item. The Work Item opens in the Work Item Editor in a new browser tab.

  2. On the toolbar, click the Actions Menu button.

  3. Hover over Change Type to, and on the sub-menu click on the type you want for the current Work Item.

  4. Save the Work Item.

Printing Documents

You can print a Document to any printing device accessible to the computer you are using. Document comments, and comment markers in the Document text are hidden in the PDF output (except when printing the Compare view in the Document history).

To print a Document:

  1. Open the Document for editing in the Document Editor.

  2. On the toolbar, click the Actions Menu button, and on the drop-down menu choose Print.

  3. Wait for the Document preview to load in the Print dialog, then click the Print button.

  4. In the dialog presented by your browser, select the target printer, set any desired print options, and launch the printing process.

Exporting Documents to PDF

You can export the content of Documents to Portable Document Format (PDF). During the export operation you can set options for page size, orientation, fitting output to page, bookmark generation, and inclusion of a header, footer and watermark. You can save the generated PDF to any accessible storage (local or network). Document comments, and comment markers in the Document text are hidden in the PDF output (except when exporting the Compare view in the Document history).

The default content of the header and footer in generated PDF documents is configurable in Administration, either globally for the repository, or for a specific project. Headers/footers can include such information as the page name, history revision number, creator's user name, the export date, current page number and total number of pages (e.g. 7/20). For information, see Administrators Guide: Configuring Documents and Pages: Configuring PDF Export.

PDF header and footer content can also be configured for individual Documents during the Export action. This is an advanced configuration requiring knowledge of XML.

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

Note

Image or Attachment Previews inserted in a document are preserved when the document is exported to PDF.

TIP

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

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

To export a Document to PDF:

  1. Open the Document you want to export.

  2. In the Document Editor toolbar, click the Actions Menu button and select Export to PDF on the drop-down menu. The Export to PDF dialog appears.

  3. In the dialog, select the desired options for the PDF document.

  4. When you have set all options the way you want them, click Export.

    TIP

    You can change the settings and quickly re-export the same Document until you close the dialog.

  5. Save or open the exported PDF according to options presented by your computer's operating system.

Customizing PDF Header, Footer, and Watermark

Advanced users who can work with XML can optionally customize the PDF header, footer, or watermark. Enable the option Include header, footer and watermark, and click the Configure... link beside it. The Configure Headers, Footers and Watermarks dialog contains an embedded XML editor, in which the XML code of the PDF Export configuration for the current Document is pre-loaded. If there is no Document-specific configuration yet, the default XML from the project configuration is loaded, which you can modify and save as the Document-specific configuration.

To include a watermark image, you must add a <watermark> element to the configuration. For detailed information on including watermarks in exported PDF documents, see Administrator's Guide: Configuring Documents and Pages: Configuring PDF Export: Configuring Export Watermarks.