Reuse a Document

Warning:

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

You can reuse an existing Document, or any revision of an existing Document., including a Document Baseline. To determine the number of a revision of a Document to reuse, review 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 — the Status field, for example.

You can reuse multiple Documents in a single operation. You can optionally keep relative links between the Work Items contained in the reused Documents.

For example, if you reuse two specification Documents where one contains functional requirements, and the other contains test cases linked to the functional requirements in the requirements specification, you can have the test cases in the reused test case specification linked to the same requirements in the reused requirements specification.

If your system or project is configured to support Document types, a reused Document is of 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 specified in the project workflow configuration.

Follow these steps 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 and choose Reuse.

    The Reuse Document dialog box appears.

  4. (Optional) If you want to reuse a revision of the Document other than the current HEAD revision, click .

    Select one of the following options in the Select Document revision dialog box:

    1. Select a Project or Document baseline from the Baseline drop-down menu.

    2. Select Revision and enter the number of the Document revision you want to reuse or click and select the revision in the Revision Picker dialog box.

  5. In the Title field, optionally specify a different title for the new Document to be created as a result of the reuse operation.

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

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

  7. By default, the new Document is 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 is 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. (Optional) Select the Remove outgoing Work Item links check box. When selected, 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 a production Document, as opposed to being some kind of library document, or a template for production Documents.

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

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

    12. 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 — from which other Documents are derived, and reuse it in projects as a derived Document. A 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 configured as read-only when the base Document was reused. Work Items contained in the base Document are duplicated in the project containing a new derived Document, and assigned new IDs. These items can then be tracked and managed as Work Items in the project containing the derived Document, which may be different from that of 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 of new Work Items, and sending of notifications about them 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, you are warned about the presence of derived Documents and offered the choice of canceling the action, or converting the derived Documents to stand-alone Documents. If you choose to convert, the link to the source Document is lost. Links between Work Items contained in the derived Document are preserved.

  • If the project is configured to support Document types and Document workflow, updating a derived Document from the base Document does not affect the type or workflow status of the derived Document.

Propagate base Document changes to derived Documents

When the content of a base Document changes, the change may be propagated to any or all derived Documents.

Caution:

Changes are not propagated automatically. This gives users the option not to propagate base Document changes to some derived Documents. The owner of the base Document should manually notify owners of derived Documents about changes that they may want to incorporate.

  1. Open the derived Document in the Document Editor.

  2. On the Document Editor tool bar, click 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

You cannot create a Derived document from a Document that contains referenced Work Items.

Mark links as Suspect

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

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

Reuse multiple Documents in a single operation

Reuse multiple Documents in a single operation can be especially useful where you have a set of standard or boilerplate Documents that need to be reused in multiple projects. The base Documents to be reused can reside in any project and space, and can be reused in any other project and space.

  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. Select the check box on the row of each Document you want to reuse, and then on the toolbar, click Reuse Documents. The Reuse Documents wizard appears.

  3. On the Selection page, select the options as desired.

  4. 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 minus icon to remove the incorrect Document's row in the table. By default, the Head revision of each selected Document in the table is 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.

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

  6. If you selected 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 when you finish the operation.

    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.

  7. If you did not select Use same project and settings for all reused Documents:

    In the Following Steps pane of the Wizard, you see a Settings item for each of the base Documents you selected for reuse. So for example, if you are reusing 3 Documents, you 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 when you finish the operation.

    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.

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