10. Configuring Documents and Pages

The Documents & Pages topic of Administration presents the following configuration options:

A related topic, covered in the chapter on Advanced Administration, is Dashboard Customization.

Configuring Document Types and Workflow

Sometimes it can be useful classify Polarion LiveDoc documents ("Documents") by type. For example, you might want to have different Document types for different types of specifications. Also, there can be a need to have workflow control over entire Documents in order to establish traceability for some process related to Documents. For example, you might want to have Document statuses such as "Draft", "Under Review", "Reviewed", "Approved", etc. and be able to transition entire Documents through these statuses.

When Document types are configured, users can assign a type to new or existing Documents in the Document Properties sidebar of the Document Editor, and view the assigned type there.

Note

Most of the default project templates have preconfigured Document types and Document workflows. (There are more project templates available on the Polarion Extensions Portal that may also have these configured). Explore whether a template can meet your needs before deciding to customize.

The default Project Templates and demo projects are pre-configured not only with Document types and workflow, but also underlying permissions that go together to help control the workflow. For example, the content of Documents of the Requirements Specification type (predefined in several templates) cannot be modified if the workflow status is inReview or Approved.

You can configure Document types and Document workflow globally and per project. Remember that the Global configuration provides the default that is used for all projects not having a project-scope configuration. Document types and Document workflow must be explicitly enabled by an administrator before the features are available to end users. The following sections explain the configuration procedures.

Security: Best Practices for Pages

Warning!

Poorly written code on a Wiki or LiveDoc ™ (Rich Text) page can leave your system open to XSS (Cross-site scripting) attacks using malicious Work Item and API calls. (Anything, Java code included, can be added to a Work Item in the document and the API will return the actual value of the target fields.)

Prevent Cross-site scripting (XSS) Vulnerabilities

  • Restrict the number of users that can modify Wiki and LiveDoc ™ (Rich Text) pages.

  • Administrators should notify any users that modify Wiki and LiveDoc ™ (Rich Text) pages of the information below:

  • Use the Rendering API (If $workItem is an instance of com.polarion.alm.shared.api.model.wi.WorkItem):

    $workItem.title.render

  • If it is not possible to use the Rendering API the use the following;

    (If $workItem is an instance of com.polarion.alm.tracker.model.IWorkItem):

    - On Wiki Pages: $esc.escape($esc.escapeForHtmlTag($workItem.title)

    - On LiveDoc ™ (Rich Text) Pages: $esc.html($workItem.title)

Setting up Document Types and Workflow

If you want to use Document types and Document workflow, you need to first set up the feature in Administration.

  1. Open the scope in which you want to enable the features (Global or some project) and enter Administration.

  2. In Navigation, expand Documents and Pages and select Document Types.

  3. On the toolbar of the Document Types page, click the Set Up Types button. (If the button is not present, it means that Document types and workflow are already enabled for the scope.)

  4. In the Set Up Document Types and Workflow dialog, click the Start button.

The setup operation will automatically copy default types and workflow to the current context. After the process is finished, you can customize types and workflow as described in the following sections.

Configuring Document Types

This configuration provides users the possibility to classify Documents according to type. It should be completed first before configuring Document workflow. For the Global scope, review the default types provided by Polarion and modify the configuration if needed to provide a common denominator for all projects. Project teams will need to decide whether the Global types meet their needs and if not, work with the administrator to modify the project configuration accordingly.

To access the configuration topic:

  1. Open the scope you want to configure (Global or project).

  2. In Navigation, expand Documents and Pages and select Document Types.

If your installation does not have Document types and Document workflow set up yet, you will see a button Set Up Types when you access the Document Types page. Click this button and follow the dialog instructions.

On the Document Types page you can...

  • Add new Document type definitions.

  • Modify existing Document type definitions.

  • Delete existing Document type definitions.

    When you delete a Document type, any Documents that have been assigned that type will display the type ID in the Type field in Document Properties. (Normally, the type name and icon are displayed in the field.)

Most of the fields should be self-explanatory. However, the following may need some clarification:

  • Default: When checked, this type appears as the default selection in the Type field when users create a new Document. Check only one type.

  • Hidden: If checked, the type will not appear in select lists and users will not be able to select it as the Document type for new or existing Documents. This is mainly for legacy types which have been applied to Documents in the past, but which are no longer valid and should not be applied to new or existing Documents. (Documents with a legacy type assigned them will keep that type as long as the type definition exists in the configuration. Users can change such Documents to any of the types not marked as Hidden in this configuration.)

Configuring Document Workflow

Note

This topic covers workflow configuration for Documents. Do not confuse this with workflow configuration for Work Items.

Workflow controls a process to ensure that no steps are missed or skipped. Workflows for Documents define and control process for entire Documents. Document workflow applies only to the Document, and is separate and apart from any workflow defined for the Work Items it contains. It enables you to trace the history of a Document's progress from inception to completion of whatever process you need for Documents.

A "workflow" consists of a set of named statuses and status transitions, transition conditions and dependencies that a Document passes through in its life cycle. For example, consider the following set of status definitions:

  1. Draft (which might be the initial status for new Documents)

  2. In Review

  3. Reviewed

  4. Rejected

If a user changes the Document's status from "Draft" to "In Review", or "Reviewed", this invokes an action ("Send to Review", for example). The action triggers a status transition, which is automatically logged in the Document's history with details such as date, time, user executing the action, etc. Actions may be configured to trigger some system function: creating a linked Work Item, or clearing some field's value, for example. The execution a workflow action can be conditional: one or more conditions are checked and must be satisfied before the user can execute the action. For example, if a Document has a custom field "Draft Finished", a function could be configured to clear that field's value when the "Back to Draft" action is executed. A condition might check that the field value is not null, or is not earlier than some specified date.

You can create and customize Document workflows and transitions in several scopes: globally (for all projects), project-specific for individual Projects, and/or Type-specific, which applies only to a specific type of Document in a project. (Type-specific can be configured both globally and in projects.) Polarion looks for the most specific workflow definition first and proceeds toward the most generic in the following search sequence:

  1. Project-specific and Work Item type-specific

  2. Global and Work Item type-specific

  3. Project-specific

  4. Global

Configuration Process Summary

Generally you will perform the following operations in the order listed:

  1. Configure Document custom fields: define any that will be needed for Documents in the scope. If your Document workflow will not have any functions and conditions that reference Document custom fields, you can skip this operation.

  2. Configure Statuses: Determine the statuses a Document can have at various stages of its lifecycle (e.g. "Draft", "In Review", etc.) and create a Status definition for each one in the Statuses section of the Workflow Designer.

  3. Configure Actions: Determine what actions are needed to transition a Document from one status to another throughout your Document authoring process, and create an Action definition for each one in the Actions section of the Workflow Designer.

    Action names appear in the drop-down list of a Document's Status field in Document Properties. The name indicates to the user what transition will take place as a result of invoking the action. For example, a "Send to Review" action might transition a Document to an "In Review" status.

    You can require users to log an electronic signature when invoking any Work Item action by checking the Requires Signature column on the respective row in the Actions table.

  4. Configure Functions and Conditions: This is optional, depending on whether or not any system functions should execute when an action is invoked by users, and if the execution should be conditional. (For available conditions and functions, see Administration Reference: Workflow Conditions and Functions for Documents.

  5. Configure Transitions: Now you can specify how the Document transitions from one status to another in the Transitions section of the Workflow Designer page.

TIP

It is recommended that you create a sandbox project based on one of Polarion's default project templates and study the Document workflow configurations for different Document types. You may find that the default configuration meets your needs. If not, you can get a better idea of what you need to customize and how to implement your custom workflow.

Using the Transitions Matrix

When defining transitions using the Workflow Designer's Transitions matrix, it's important to keep two things in mind:

  • You are defining what transitions are allowed between any 2 Statuses.

  • Therefore, you don't need to specify an action for every transition... just those transitions you want to allow to occur between 2 statuses.

Consider an example of a workflow for a Requirements Specification. Assume that, among others, the statuses Draft and In Review are defined.

It makes sense to allow transition from the Draft status to the In Review status, so at the intersection of these two, you specify the Send to Review action (which has already been defined in Actions).

Assuming the organization's authoring process does not allow transition directly from Draft to Reviewed, it would not make sense to specify Send to Review where Draft intersects Reviewed in the matrix. No action would be specified, and the transition cell should be left empty.

For some statuses, you may want to allow more than one possible transition. For example, suppose you have the status definitions Draft, Reviewed and Rejected. For Documents having the In review status, let's say there are three possibilities in the process: a stakeholder can approve the Document and give it the Reviewed status, or decide to send it back for changes, giving it the Draft again, or reject the Document and give it the Rejected status. The workflow can be configured to support this process but allowing 3 transitions on the In Review status.

  • Transition from In Review status to Draft status via the Back to Draft action.

  • Transition from In Review status to Reviewed status via the Reviewed action.

  • Transition from In Review status to Rejected status via the Reject action.