Configure 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:

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

  • In Review

  • Reviewed

  • 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 to the Document's history with details such as date, time, user invoking 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 processing of a workflow action can be conditional. One or more conditions are checked and must be satisfied before the user can invoke the action. For example, if a Document has a custom date-time field named Draft Finished, a function could be configured to clear that field's value when the Back to Draft action is invoked. 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 perform the following operations in the following order:

  1. Configure Document custom fields — Define any fields that are 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 — Draft, In Review, Approved, for example — 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, an action named Send to Review might transition a Document to a status named In Review.

    You can require users to log an electronic signature when invoking any Work Item action by selecting the check box 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 run when an action is invoked by users, and if the running should be conditional. (For available conditions and functions, see 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

Use 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 two Statuses.

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

Consider an example of a workflow for a requirements specification Document. Assume that, among others, the statuses Draft andIn 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 Sent 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 status again, or reject the Document and give it the Rejected status. The workflow can be configured to support this process but allowing three 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.