Configuring Document Signatures

Some organizations have a formal review and sign-off process for specifications and other documents. Such a process can be supported in Polarion using electronic signatures, including secure signatures compliant with common regulatory standards. This is accomplished in the Document Workflow configuration. You can set the Requires Signature option on any configured Document workflow action - an action such as "Mark Approved", for example. Some additional parameters can be set specifying a signature policy. It is also possible to configure a default set of invited reviewers/signers via a workflow function with appropriate parameters.

When this option is set for a Document workflow action, the action cannot be invoked by Document users, and the Document cannot transition to the next status in the workflow until the necessary users have added their electronic signature, and the signature policy is satisfied. For an example, if the workflow has an action "Mark Approved" which transitions the Document to the status "Approved", the status transition is blocked until invited reviewers have signed off, and the signature policy is met. If the policy requires that all the invited signers must sign, the transition is blocked until all invited people have electronically signed approving the transition.

TIP

Document-related signatures are U.S. CFR 21 Part 11 compliant secure electronic signatures.

For security, it is highly recommended to use the https protocol for access to Polarion when your system is configured to use electronic signatures.

You can configure any Document workflow action to require signature(s) before the status transition. Whether or not a given workflow action requires signatures depends on the process adopted by the project team or organization. Different stages in the process may require the signatures of a different set of signers, which means there could be several rounds of review and sign-off before a Document is considered "final" or "approved". It is the role of the Document owner or manager to decide which action or actions require signatures, to invite people to review and sign electronically, and after all signatures are collected, to transition the Document to the next workflow status. The administrator's role is to configure the Document workflow according to the required process, and to configure the Requires Signature option for the action or actions that require signatures.

For additional information see the User Guide topic Signing Documents.

Process Overview

The main steps in the process to configure Document signatures is as follows:

  • Configure Document types. The project owner or leader should decide what types are needed for the project. Some default types are pre-defined in most project templates. You can modify the default types, add new types, or remove existing types as needed to meet the needs of the project. For information, see the Administrator's Guide topic Configuring Document Types.

  • Configure Document workflows. Again, the project management should specify their process for each Document type - what statuses each Document type can have, and the actions that can transition the Document to them. You create a workflow configuration that applies to all Document types, and type-specific workflows for different Document types. For information, see the Administrator's Guide topic Configuring Document Workflows.

  • Configure workflow actions. Your project management should specify which Document workflow actions in which Document types require signatures before the actions can be invoked by users to transition the Document status. The following sections explain how to do this.

Configuring a Workflow Action

This section assumes that Document workflow has already been configured according to the requirements of the project leader or manager, who has also specified which workflow actions must require signatures before the Document status can transition, and the signature policy.

To access the configuration:

  1. Log in with administrator permissions for the scope you are configuring (global, or a specific project) and enter Administration.

  2. In Navigation, expand the Documents and Pages topic and select Document Workflow.

  3. Assuming that Document types have been defined as previously discussed, click the Edit button on the row of the type you want to support signatures. (If the workflow and signature policy are the same for all types, then edit -- All Types --.)

  4. Scroll the page until you see the Actions section. This is where you configure one or more workflow actions to require signatures.

Enabling Signatures

The Actions section of the page is formatted as a table. Each configured workflow action occupies a row. The table has a column named Requires Signature, which contains a check box. Locate the row of the action(s) that must require signatures, and check this box.

When you check Requires Signature, two additional fields appear in the column (see figure below).

  • Signature policy list

  • Signer role option

TIP

Depending on your screen resolution, you may need to resize the Requires Signature column wider to see these fields. Drag the column separator in the column header.

Figure 10.1. Enabling Signatures on Workflow Action

Enabling Signatures on Workflow Action

How to enable signatures and set signature policy on a workflow action

The signature policy options provide some restrictions on when the workflow action can be invoked. Hints appear when you hover over an item in the list, which should be mostly self-explanatory. The No Policy item is the least restrictive. It means that the Document owner can invite people to review and sign a Document before it transitions to a new Status, but the owner can invoke the workflow action and change the Document status whether or not anyone signs. For example, the team's process might specify that if no one signs a specification within 5 business days after being invited, Documents can move forward in the process. If some invitees do sign the Document, that will be recorded in the history.

The signer role option provides and optional additional datum that may be desirable in some situations, particularly in regulated environments. When enabled, you can specify the role of the people who sign the workflow action. The actual value should be specified by the project owner along with the other signature requirements. For example, if signatures are required to transition a Document from "Draft" to "In Review", a value such as "Team Leader" might be appropriate. If signatures are required to transition from "In Review" to "Approved", a value like "Project Lead" or "Analyst" might be specified.

Automating Invited Signers

This is an advanced topic requiring some familiarity with Workflow functions and conditions. In cases where the set of people who should always be invited to sign workflow actions is static, you can configure the action with the AddDefaultSigners function. The function selects users according to its parameter settings, and adds them to the list of invited signers in the Signatures sidebar when the Document enters the relevant status. The users may be specified in function parameters as a list of user IDs, or a list of user roles, or both.

For example, suppose the same users should always be added as signers when a requirements specification Document enters the "In Review" status. These users must all sign before the "Mark Approved" action can be invoked, and the Document transitioned to "Approved" status. Further suppose that all these users have the role "project_approver" assigned to them for the project. You can specify that role in the relevant function parameter (details below), causing all users with that role be added as invited signers when a Document enters a Status from which that Action is allowed in the workflow configuration.

Suppose that in addition to people with the "project_approver" role, one or two other people should always be added as signers for the workflow action. You can specify their user IDs in another function parameter, and they will also be added.

To configure automatic addition of invited signers:

  1. Before starting, make a note of the user role(s) and/or user IDs you want to specify in this configuration.

  2. Open the Workflow Designer (Administration: Navigation: Documents and Pages: Document Workflow) and edit the Document type you want to configure. The Requires Signature option should be checked, and the signature policy selected.

  3. Click the (Edit) icon on the action's row to open the Details for Action dialog.

  4. In the Functions section, select AddDefaultSigners in the Functions column.

  5. Click the (Edit) icon to open the Parameter for dialog.

  6. If default invited signers should have a specific role, then in the Name column enter the function parameter name: signedBy.roles, and in the Value column enter one or more user role IDs. For example, project_approver. If you specify multiple role IDs, separate them with a comma.

    If you want default invited signers to be specified explicitly, then in the Name column enter the function parameter name: signedBy.users, and in the Value column enter one or more user IDs. If you specify multiple user IDs, separate them with a comma.

    Note that you can specify both parameters. For example, the "project_approver" role might add all but one or two necessary people as default reviewers/signers. Supposing that the other people have a different role, but not everyone with that role is needed, you can add just the IDs of the necessary users in addition to people with the specified project role.

  7. Click Close in both dialogs and save the Document workflow configuration.

Figure 10.2. Specifying Default Document Signers

Specifying Default Document Signers

User Document workflow function and parameters to add a default set of reviewer/signers to an action

IMPORTANT

Users with the specified roles and/or IDs are only added to the list of invitees who should sign a workflow action. These users are not automatically notified to review and sign. The Document owner or manager must still contact the invitees at the appropriate time and invite their review and sign-off. (See the User Guide topic Inviting People to Sign.)

See also: Administrator's Reference: Workflow Functions (Documents).

User Permissions for Signatures

There are two configurable permissions in Administration > User Management > Permissions Management that you can set to control which users can sign Documents:

  • Permission to SIGN/DECLINE - this permission allows user to sign or decline document

  • Permission to MANAGE SIGNATURES - this permission allows user to invite/remove signer or reset verdict on document

These permissions can be set in global and/or project configuration. They work for Documents and also Custom sets of Documents, and they are also applicable for the dynamic role document_author.

Document Signatures Custom Set

In projects based on Polarion Project Templates, requirements specification type Documents are tied to a permissions Custom Set named Submitted and Released Requirements Specifications. The permissions allowing modification of this type of Document are denied for most roles. This, in effect, makes the Document read-only when the workflow status is any except Draft.