Signing Documents

Polarion supports a process of review and approval of individual Work Items, such as requirements. These may be contained in Documents, or created directly in the Work Item Tracker. (For more information, see User Guide: Reviewing and Approving Work Items. However, it can be desirable for regulatory and other reasons have such a process for entire documents, such as requirements or design specifications.

Polarion can support your formal document review and sign-off process for specifications and other types of documents, using secure electronic signatures compliant with U.S. 21 CFR Part 11. A Polarion administrator can map your review and sign-off process to the Document workflow configuration. Each step in the process can optionally be set up to require one or more electronic signatures before the a Document can move to the next stage in the workflow.

Overview of Document Signature

Consider a simple example. Suppose a requirements specification Document goes through three stages before the requirements can be implemented in production: "Draft", "In Review", and "Approved". These "statuses" can be mapped by an administrator in the project workflow configuration for Documents of the type "Requirements Specification". (It is possible to configure as many Document types as you need. You might have more granular types like "System Requirements Specification", "Functional Requirements Specification", etc. or types like "Risk Analysis"). The Document owner or manager can invoke "actions" to move the Document through the process from one status to the next. These can also be defined in the Document workflow configuration, and could be something like:

  • Send to Review - this action moves ("transitions") the specification Document from the "Draft" status to the "In Review" status.

  • Mark Approved - this action moves ("transitions") the specification Document from the "In Review" status to the "Approved" status.

TIP

Polarion includes project templates that have Document types and Document workflow already configured. The templates are based on input from actual users and are designed to meet the needs of a broad range of projects. Both project templates, and projects created from them can be customized to meet user-specific requirements.

In an SSO Environment

Under normal circumstances, with SSO (Single Sign On), users will not have to enter their credentials anywhere in Polarion if they’ve logged into an associated SSO account.

E-signatures are an exception. Because e-Signatures require that users provide two distinct tokens when signing their electronic signature, an alternative LDAP authentication via a direct LDAP connection needs to be configured.

  1. Go to the LDAP Configuration page.

    ( Administration Global Administration User Management LDAP Configuration)

  2. Make sure that the “LDAP Server Connection Settings” are configured.

    (See the Configuring Single Sign-on section and the Windows and Linux installation guides for details.)

  3. Tick the “Allow for e-Signatures” box in the “Alternative Authentication via LDAP in a Single Sign-on Environment” section.

  4. Click Save.

Regulatory Compliance

For regulatory compliance, it is necessary to record who reviewed the specification Document, who approved it, and when. The administrator can configure the "Mark Approved" action to require signatures, and a "signature policy" such as "all invited reviewers must sign", or "at least one invited reviewer must sign." When so configured, no one can set a requirements specification Document's status to "Approved" until all the necessary signatures have been registered.

Prevent Your Browser from Saving Passwords in Chrome

Administrators should ensure that all their users have password saving turned off in Chrome to comply with U.S. 21 CFR Part 11 and other regulatory standards governing electronic signatures.

Electronic signatures for Documents are compliant with United States Code of Federal Regulations, Title 21 Part 11. Users who sign a Document workflow action are shown a dialog advising them of the significance of their signing action, and prompting them to enter their password to confirm their signature and identity. A record of each signature, including data that makes it CFR 21 Part 11 compliant, is recorded automatically in the Document history.

Figure 15.41. Secure Signature

Secure Signature

Electronic signatures comply with 21 CFR Part 11 electronic signatures

Process and Versions

To collect signatures, the specification Document's owner or manager invites people to review and sign it by sending them an email containing a link to the Document in the Polarion portal. (All invitees must have user accounts and the permissions required to access the Document, and sign or decline to sign Documents.) Each reviewer is presented the option to sign or decline to sign. They can also post comments. After all the necessary signatures have been registered, the Document owner or manager can invoke the "Mark Approved" action in the Document properties, and the Document will transition to the "Approved" status.

The signature process can support multiple versions. For example, the specification may be approved for production, but while production is going on, work resumes on the specification, adding new requirements for new features or enhancements to existing features. The specification Document in the "Approved" state becomes read-only. But is not necessary to create a different Document to continue development. The workflow can be configured with an action like "New Version" which branches the approved Document, which can then be tagged with a version identifier and modified as needed for the next round of production. The previous version in its Approves state, is automatically preserved in the Document history. The project manager might also create a Baseline of the project at the point which the specification was signed as approved.

The rest of this chapter provides information for different roles:

Information for Authors and Managers

This section contains information for authors and/or managers of specification or other Documents. It covers what you need to know in order to set up a review and sign-off process for your Documents.

Start by working with the Polarion administrator for your project to review the Document Types and Document Workflow configurations to make sure the types you need exist, and that each type has your process mapped in the workflow. Decide which transition action(s) must require signatures, and have each action configured accordingly in the Document workflow configuration. Information for administrators is provided in the Administrator's Guide topic Configuring Document Signatures. Depending on the project template used to create the project, very little if any modification may be needed.

With the Document signatures configuration in place, there is nothing more to do except develop your Document up to the point where it is ready for the workflow transition that requires signatures (or the first such, if there is more than one). For example, your Document starts with "Draft" status, and at some point is ready for review and approval. Following the simple scenario described earlier, you would invoke the "Send to Review" action. The action is enabled in the Status field in the Document Properties because that action was not configured to require signatures in order for the transition to "In Review" status to take place.

However, you see that the next action, "Mark Approved", is disabled in the Status field. This is because the action is configured to require signatures. You won't be able to invoke that action and transition the Document to the "Approved" status until signatures have been logged. It is at this point that you need to invite people to review and sign your Document.

Inviting People to Sign

Everyone you invite must have a Polarion user account, and have permission to read Documents in the project. Otherwise, they will not be able to see your Document and will get an error message if they follow a link leading to it. All reviewers must also be assigned the project role that has been granted permission to SIGN/DECLINE for Documents. Otherwise, they will not appear in the list of people you can invite to review and sign your Document. (Permissions and roles are assigned by the Polarion administrator.)

To invite people to review and sign:

  1. Open the Document in the Document Editor, and open the Signatures sidebar.

    The sidebar shows a panel labeled with the name of the workflow action that requires signatures. In the case of our running example, that would be Mark Approved.

  2. Click on the action name. The sidebar shows two page tabs and a button.

    Figure 15.42. Signatures Sidebar

    Signatures Sidebar

    Invite people to review and sign a Document

  3. Click the Invite for Signature button.

    In the dialog, select the first user you want to invite from the user names in the drop-down list.

  4. If you want to invite another user, click the icon, select the user in the list, and click again.

    Repeat until you have added all the users you want to invite.

    TIP

    Keep in mind that you will not be able to invoke the transition action until the configured signature policy is satisfied. For example, if the policy requires all invited users to sign, the action cannot be invoked until all have logged a signature. If it requires that at least one must sign and none must decline, then that condition must be satisfied in order to invoke the action.

    You can view the signature policy in the All Signatures tab of the Signatures sidebar (shown after you click on an action name - see the previous figure).

  5. At the bottom of the dialog, select the URL in the Link for Invitees text box and copy it to your clipboard.

  6. Click OK to close the dialog, and then Save the Document.

  7. Open your email client program, or internet chat, etc. and compose a message to all the people you invited, asking them to review and sign the document. Paste the URL from your clipboard into the message body.

Figure 15.43. Select Invitees

Select Invitees

All invitees specified. Copy Document URL to send to invitees.

Figure 15.44. Message to Invitees

Message to Invitees

Send a message to your reviewers including the Document URL.

Automating the Invitees List

Your administrator can pre-define the list of invitees for any Document workflow action, so that the Document owner/manager does not have to add invitees manually for every new Document. Invitees can be added according to their user role in the project, or explicitly by their user ID. You might want to consider having custom user roles defined for your project and have those roles assigned to the people who routinely review and approve specifications or other kinds of Documents.

Monitoring Signatures

You can monitor the progress of collecting signatures in the Signatures sidebar of your Document. The sidebar shows which invitees have signed, which have declined, and the names of all invitees.

The All Signatures tab of the sidebar shows this same information, plus the signature policy. The latter is helpful in understanding how close you are to satisfying the policy. If the signature policy is currently satisfied, a message is displayed indicating this, and a link is provided which opens the Document Properties sidebar where you can invoke the action to transition the Document in the Status field, where the action will now be enabled. Be sure to save the Document after changing the field.

Figure 15.45. Monitor Signature Progress

Monitor Signature Progress

Use the All Signatures tab of the Signatures Sidebar to monitor the progress of signature collection

Restarting the Process

Sometimes feedback from invited signers will result in further work on the Document being required, and a fresh round of reviews started. The Document owner/manager can reset signature status of "Signed" or "Rejected" for the current workflow transition back to the "Pending" state by clicking on the X icon on the right part of the signature Statistics. The Reset action is available only in the All Signatures panel for a specific workflow transition (i.e. not in "My Signatures", and not in Entry Point). It is not available after the Document status has been transitioned. You can see recalculated signature statistics immediately without saving the Document.

In cases where a Document needs to be reworked, or a signature was declined, the author or owner may decide that signatures up to that point are obsolete and a new round of reviews and signatures is needed on a new, reworked Document version. To accommodate such scenarios, an administrator can configure the workflow action that sends the Document back to the authoring status (e.g. "Back to Draft") to execute a workflow function that marks the current signatures as obsolete.

Completing the Process

After all signatures needed to satisfy the signature policy have been logged, the Signatures sidebar displays a message indicating that the Document can now be transitioned to the next Status. You as the Document owner, author or manager must explicitly take this action.

To transition the signed Document:

  1. Open the Document Properties sidebar.

  2. Click the drop-down control of the Status field.

  3. Select the signed workflow action in the list. The list item should now be enabled.

  4. Save the Document.

Note

To be able to transition the workflow, you must have the MANAGE SIGNATURES permission for Documents (assuming your system has the default configuration of workflow signatures).

Figure 15.46. Transition After Signatures

Transition After Signatures

When signature policy is satisfied, workflow transition action is enabled

TIPS

When the signature policy is satisfied, the All Signatures tab of the Signatures sidebar displays a link that, when clicked, opens the Document Properties sidebar, where you can change the Document Status.

In projects based on Polarion Project Templates, requirements specification type Documents are preconfigured with Document workflow and permissions settings that make such Documents read-only once they have reached any other than the Draft status in the workflow. The prevents modification of any Requirements Specification Document that was submitted for review or approved. Documents can be branched to store the approved version of Document for implementation, while the master specification can be worked on for a subsequent version or release. (For technical details, see the Administrator's Guide topic Configuring Document Signatures: Document Signatures Custom Set.)

Information for Reviewers and Approvers

This section contains information for people invited to review and sign off on specification and other Documents. It covers what you need to know in order to find Documents you are asked to review and approve, how to sign a Document, your option to decline to sign a Document, and what happens after that.

Accessing a Document

Normally you will receive an email or other electronic message from the owner of a specification or other Document requesting your review and signature. This message should contain a link to the Document in your organization's Polarion portal. Simply click on the link to open your default web browser and navigate to the Document in the portal. If you are not already logged in, you will need to do that, after which the Document you need to review will open. The Signatures sidebar should be visible, and the My Signatures tab selected.

Figure 15.47. Signature Options for Document Reviewers

Signature Options for Document Reviewers

How to Sign or Decline and Save

If you are already logged in to the portal, Documents awaiting your signature are listed (with links) in your My Polarion page (assuming the page has not been customized to remove the listing).

Signature Options

After you have reviewed the Document, you have three options:

  1. Sign - by clicking the Sign button in the Signatures sidebar. You can optionally add a comment.

    By this action you signify that you agree that the Document in its current state can transition to the next step in the workflow.

  2. Decline - by clicking the Decline button. You should also add a comment stating your reason(s) for declining.

    By this action you signify that you do not agree that the Document in its current state can transition to the next step in the workflow.

  3. Add Comment - without signing or declining. If you have questions or discussion for the document author or other stakeholders.

    By commenting only, with no other action, you may be blocking the Document from moving to the next step in the workflow, depending on the signature policy configured for the action you are asked to sign. You can see the signature policy in the All Signatures tab of the Signatures sidebar.

Important

After taking one of the above actions, be sure to click the Save button on the Document Editor toolbar, or use the Save keyboard shortcut to save the Document. If you leave the Document without saving, your signature action and any comments will not be logged.

What Your Signature Means

When you sign a Document, you are not necessarily signifying final approval of the Document. You are only signifying that you agree that it can move to the next stage of the development process, as configured in the project workflow. For example, you may have been asked to sign the workflow action "Send to Review", that transitions the Document's status from "Draft" to "In Review". By signing, you signify that you agree that the Document is ready to that transition.

Document-related signatures are U.S. CFR 21 Part 11 compliant secure electronic signatures. When you click Sign, a dialog will appear with a message asking you to explicitly enter your user name, followed by one asking for your password (two steps ensure the electronic signature is compliant).

Figure 15.48. Secure Signature

Secure Signature

Secure signatures are compliant with U.S. 21 CFR Part 11 and other regulatory standards

The automated Document history will record the data required for regulatory compliance, including your user name and the date-time of your signature.

The action may be configured with a "signature policy", such as "all invited users must sign". Even if your signature results in the signature policy being satisfied, the action of signing does not actually execute the workflow action and transition the Document to the next Status. The Document author or owner or manager must explicitly execute the transition in the Status field of the Document Properties sidebar.

Additional Information Related to Signatures

This section provides some additional information about Document and Document workflow signatures.

Signature Comments

Throughout the process of obtaining signatures for various Document workflow actions, stakeholders can have discussions by posting comments that pertain specifically to the signature process. Such Signature Comments have several commonalities with comments not related to the signature process (i.e. Document Comments):

  • People can reply to a given comment.

  • There can be multiple comment threads.

  • Comments can be marked as Resolved.

  • The comments appear in the Comments sidebar, and clicking on a comment marker in the text opens that sidebar, focusing the comment.

  • The same options are available by clicking the (Pane Settings) icon on the sidebar header.

However, Signature Comments are created in the Signatures sidebar, in the Signature Comments section, using the Add Comment button. They become part of the history maintained for the Document signature process. The Signatures sidebar shows only unresolved Signature Comments, allowing signature stakeholders to find them easily and not be distracted by Document Comments.

Users must be granted the permissions required to create, reply to, and resolve comments in order to perform these operations.

TIP

If you have already signed a transition and logged the required signature comment, and the Document owner subsequently resets the signature process, your previous signature comment must be marked "Resolved" before you can sign the document again. If necessary, you will be prompted to resolve your previous comment when you sign the Document again.

Signature Information in Documents

You can optionally display a panel of information about the current status signatures in the body of a Document. The #documentPanel macro, when used in a Classic Wiki content block in a Document, renders an overview of Document Properties as well as overview of Document Signatures for the current version of the Document.

Figure 15.49. Signature Information in Document Body

Signature Information in Document Body

Using Classic Wiki macro to display signatures state and other metadata in Document body.

To implement the panel:

  1. Place the insertion point on the line where you want the panel to appear... after the Table of Contents, for example.

  2. On the Document Editor toolbar, click the Insert drop-down control, and choose Wiki Content.

  3. In the Wiki Content dialog, enter the documentPanel macro with the desired parameters and click OK. (For details on parameters, see Syntax Help in the Classic Wiki Editor.)

    Example: #documentPanel(true "approved") - shows Document signature that are not done yet, and specifies the ID of the workflow status representing the final approved status of the Document.

TIP

Classic Wiki Syntax Help is normally available on your Polarion portal at a URL like the following:

http://[POLARION SERVER NAME].[YOURDOMAIN].com/polarion/#/wiki/Doc/SyntaxHelp

Signature Information in History

Changes in Document workflow signatures are shown in Document history when comparing two revisions. Information is shown in the Fields section.

Each of the workflow signatures, is shown on separate row and associated visually with the status signed. The same rendering is shown in email notifications.

Accessing Signed Revisions

When you open the Signatures sidebar, it shows all signed transitions - those for which the signature process is complete. Clicking on a name opens a historical view of the Document in the state it was when the transition was signed.

Figure 15.50. Signed Transitions

Signed Transitions

Querying on Document Signature

This is information for developers and advanced users who need to know how to formulate and execute queries on Document signatures. Two indexed fields are available for searching for Documents by signature.

  • signatureState - the overall state of the active workflow signature (i.e. for the next workflow transition). The goal is to be able to easily query Documents that are in certain state of the signature. Possible values: pending, declined, ready

  • signatures - search for Documents by individual signatures and their outcomes for the active workflow signature (i.e. for the next workflow transition). The goal is to be able to easily query for Documents that are waiting for my signature. Possible values: pending, signed, declined

    Syntax: signatures:[VERDICT]=[USERID OR *]

Examples:

  1. signatures:invited=$me ($me variable work only in Wiki) OR signatures:invited=$[user.id]

    Dollar sign needs to be escaped in Classic Wiki as \$. Search all Documents where current user is invited to sign the active transition.

  2. signatures:signed=* - Search all Documents for which the active transition has been signed by any user.

  3. signatures:declined=bJones - search all Documents for which the active transition has been declined by user "bJones".

Usage:

  1. Pages macro in Classic Wiki

    {pages:query=signatureState:pending|display=list} or {pages:query=signatures:invited=admin|display=list}

  2. Table Widget in LiveReport Pages.

  3. Polarion open API.

Signatures and Branched Documents

If you branch a Document that has signatures configured in its workflow, you can optionally include the signatures. The Branch Document dialog provides an option, Copy Status and Workflow Signatures that controls whether signatures are copied. If the option is checked, then on the branch action does the following:

  • Document status is copied

  • All completed ("done") signatures and the transition revision are copied, and tagged to show that they are copied from a different Document.

  • Any still open signatures are copied and all the signature verdicts are reset. Signature comments are not copied.

Branching with workflow and signatures is only available from a specific Document revision, not the HEAD revision. If you try to branch the HEAD, you are automatically switched to the last revision and asked to confirm the switch.