15. Working With Documents

Documents combine the ease of use of desktop word processing applications with the power and scope of a data-driven tool. Your ability to work with Documents is controlled by permissions granted to your user role in projects. You may have different roles in different projects, and your access level may vary according your role. For example, you may be able to create new Documents in one project, but not in another project. Should you find that some feature seems to be missing, or you cannot perform some operation, check your permissions with the project administrator. For information about what permissions you need to have for different actions, see the User Reference topic Permissions and License, especially the sub-topic Permissions for Document Actions.

Creating a New Document

Creating a new Document in your Polarion portal is as simple as creating a new document in your favorite word processor application. Documents for a project are stored in one or more spaces under the Documents and Pages topic in Navigation. You can locate them easily either by browsing the Documents in Navigation, or using the Navigation pane's filter box, which provides incremental search of your project content.

There are two ways to create a new Document in Polarion:

  • Create a new empty Document in the Polarion portal using the New Document feature.

  • Create a new Document by importing an existing Microsoft Office Word™ (referred to in documentation as "Word") document using the Import from Word (or "Word Import") feature.

Spaces and Subspaces

As of Polarion 18.1, you can create a hierarchy of nested folders (Spaces and Subspaces) for new documents.

Note

Five levels of nested subspaces and up to 250 artifacts within each of them are officially supported.

TIP

Plan and create your Space and Subspace hierarchy BEFORE creating documents., to avoid any move restrictions.

When creating documents in Polarion for the first time, it's a good idea to plan out how you would like to organize them beforehand. Unlike Word documents, Live Documents and Live Reports are integrated with a vast array of possible widgets, potentially thousands of Work Items, and in the case of Live Documents, a powerful version history.

This diversity of integrated external content can lead to move restrictions, so its a good idea to organize your Spaces, and Subspaces from the start, to avoid any potential move restrictions.

Note

You can move Live Documents once they're created, but you cannot move Live Report, Info or Wiki pages.

A Nested Spaces Hierarchy

Create a Nested Space Hierarchy:

  1. Click on Documents and Pages in Navigation.

  2. Click on the top left.

    - If you've clicked on an existing Space or Subspace, click Expand Tools at the top then and click Create New.

    - If you've clicked on an existing, top level, Space, click Expand Tools at the top then and click Create New.

    - If you’ve clicked on the Index, click on the top left.

  3. Click Create New Space.

  4. Enter a Space Title, a Space Name and select the Parent Space that you would like the new Space to appear in.

    (If you've already created a Subspace within a Space, then the hierarchy will appear within the drop-down list.)

  5. Click Create.

  6. The new Space appears in the navigation bar's Space hierarchy.

  7. Now when you create a new Live Document, Live Report, Info or Wiki Page , you can select any Space or Subspace in the Space drop-down menu.

    (Live Documents can also be moved to a Space or Subspace)

Note

Hierarchical spaces created in the Polarion do not actually create physical nested folders within the repository.

Rename or Delete Space/Subspace

Rename a Space/Subspace
  1. Click on Documents and Pages in Navigation.

  2. All existing Spaces appear in a list.

    (You can view their hierarchy in Navigation.)

  3. Click to the right of the Space you want to rename.

  4. Enter a new Title.

    (The Space's ID cannot be changed.)

  5. Click Save.

  6. The updated name appears in Navigation.

Delete a Space or Subspace

Warning

If you delete a Space any Documents or Subspaces, within it will also be deleted, and cannot be restored.

To Delete a Space:
  1. Click on the Index of the Space you'd like to delete.

  2. Click and select Delete (Space_Name).

  3. The Confirm Delete dialog appears.

  4. Click OK.

To Delete a Subspace:
  1. Click on the Index of the Space that contains the Subspace you want to delete.

  2. Tick the box beside the Subspace(s) to delete.

  3. Click Delete on the right.

  4. The Confirm Delete dialog appears.

  5. Click OK.

Creating Empty Documents

Create new empty Document when you want to create new content like specifications (or any other type of document which will contain Work Items), and you do not already have the content in a Word document that could be imported. (For information on importing a Word document, see Importing Word Documents.

When you create a new Document, you will use the Document Editor to write and format the content. The current state of the Document is online at all times. You can share the Document's URL with other Polarion users, and other users can collaborate on the content. (Users must have the necessary permissions to access the project and the Document). You can also use the Round-trip for Microsoft Word feature to share the Document with external stakeholders who do not have access to the Document in your Polarion portal. For information see Sharing Documents.

Either during the authoring process, or when it is complete, you can use tools in the Document Editor to mark portions of the document content as Work Items and link the Document's Work Items for structure and traceability. For information, see Editing a Document: Work Items in Documents.

To create a new Document:

  1. Open the project to which the new Document will belong. (See User Guide: Accessing Projects.)

  2. In Navigation, click on Documents and Pages. The topic's home page loads in your browser.

  3. In the toolbar at the top of the page, click the Create New button and choose LiveDoc Document. The Create LiveDoc Document dialog appears.

  4. In the Create LiveDoc Document dialog, fill in the fields (see User Reference topic Create LiveDoc Document Dialog for more details):

    • Title: The human-readable Document title. Non-ASCII characters may be used.

    • Name (ID): An identifier (ID) unique withing the current project and space. Used by the system for indexing and other purposes. Only ASCII characters may be used.

    • Type: Choose from a list of available Document types. (This field is present only if Document Types are configured for the project).

    • Space: Select the Space or Subspace where the new Document will be located.

    • Work Item Type: Select the main type of Work Item the new Document will contain. (More types can be added later... see Multiple Work Item Types). The drop-down list contains the Work Item types defined in your project configuration.

    • Link Role: Select the default link role that should be applied to hierarchically structured Work Items in the new Document.

      For example, if you split a paragraph marked as a requirement so you have 2 separate requirements, and you then indent the second paragraph, this option controls what relationship is applied between the indented requirement paragraph and the preceding requirement paragraph. Typically the indented paragraph is a child of the preceding, so the default selection has parent is what you want. Note that this is just the default: you can apply any configured link role later on when editing the Document.

    • If you want the Document's headings to have outline numbers, check the Enable Outline Numbering box and optionally enter a prefix value in the Prefix field.

  5. Click OK to create your new Document. The new Document is loaded and displayed in the Document Editor ready for editing. Before beginning to work on the new Document, you may want to check the configuration that controls how the Document will display Work Items, which you can access by choosing Configure from the drop-down menu of the Work Item type icon in the Document toolbar. For more information, see Multiple Work Item Types later in this chapter.

Add Remote Links to a LiveDoc

Polarion supports the linking of remote data from other tools, like SIEMENS' Teamcenter.

Linked Data can be used to:

  • Create links for Work Items or LiveDocs from objects that reside on external tools. (Act as Link Data consumer.)

  • Link Polarion LiveDocs to objects that reside on external tools. (Act as a Linked Data provider.)

(This is generally done by creating or selecting a remote object in a "delegated UI" provided by the Linked Data provider.)

Once "Linked Data Friends" are configured by an administrator, they appear as an icon in the Linked Work Items section of a Work Item.

Add an External Linked Data Item

  1. Select the target Project.

  2. Click Documents & Pages in the navigation bar.

  3. Select an existing LiveDoc or create a new one .

  4. Click then Document Properties.

  5. Click Edit Links at the bottom of the sidebar.

  6. Select the link's role and click Link External Item (Linked Data).

  7. Select a location from the drop-down list.

  8. Click Allow.

  9. Click Select an Existing Item... and select an option.

    (Or Create New Item... to create a new item in the external application.)

    Note

    Create New Item.. will launch the external Linked Data application in a pop-up window.

    (The workflow to create a new Item will vary depending on the application.)

Example: Existing Item from Teamcenter:

  1. Select Teamcenter from the "Location" drop-down box and click Select an Existing Item....

    (Teamcenter appears in a pop-up window.)

  2. Select an item from the list on the left. (An overview of its details appears on the right.)

  3. Click OK.

  4. The item is linked to the Polarion LiveDoc.