Reviewing and Approving Work Items

Polarion supports a formal approval process for any type of Work Item through the Approval Center feature. The pre-configured project templates delivered beginning with version 2013-SR1 have pre-configured support for approvals. This chapter provides an overview of the capabilities, explains how to configure a project to support approvals, and how to perform various tasks involved in formally approving Work Items.

Approval Center Overview

The "out-of-box" approvals support delivers several features and capabilities for organizations that need a formal approval process with an audit trail.

  • Workflow Integration: Approvals are integrated into the workflow of Work Items, including all types of requirements. Approvals can be added to the workflow of any Work Item type that does not already have it, including your own custom types. Integrating approvals into the workflow ensures that steps and people are not skipped or bypassed in the approval process.

    Workflow also automates some tasks, such as designating users as Approvers, and notifying them to review and approve items. For example, when a Work Item transitions from an initial draft status to a ready for approval status, a specific list of users, and/or all users whose user profile includes a certain role can be automatically designated as Approvers. These users' names are added to the Approving Users list in the Approvals field of the Work Item, and email notifications are sent to them.

  • History and Audit Trail: An automatic, reportable history of the approval process is automatically maintained, so it will always be possible to find out who approved what and when.

  • Easy for Approvers: The Approval Center is designed to facilitate users who have been designated to review and approve or disapprove items:

    • Links in email notifications lead users directly to items they should review and approve or disapprove.

    • The portal user interface makes it fast and simple for any user to access the items awaiting his/her approval.

    • Approvers can approve or disapprove multiple items at once in a single operation.

    • Approvers can discuss items with other stakeholders in threaded Approval Comments.

    • Approvers can choose to work in a document interface (assuming the items are contained in a LiveDoc Document) or in the Tracker tool.

    • Organizations can obtain inexpensive Reviewer licenses for use by people whose only role in projects is to review and approve Work Items. The Reviewer license also enables users to review and approve Work Items on Apple iOS mobile devices using Polarion's ALM2GO app.

  • Easy for Managers: The Approval Center also helps project managers, team leaders, and others to track and manage the approval process:

    • Easily review, respond to, and resolve Approval Comments, as well as create new Approval Comments.

    • Hide or reveal resolved Approval Comments.

    • Explicitly invite users to review and approve items via email or instant message.

    • Quickly review the current state of the approval process for any item in real time.

    • Reopen approvals for revised items that were disapproved, removing the disapproval state and starting the review and approval process again.

Getting Started

Before starting to use the Approval Center feature, there are some preliminary issues with which you should become familiar:

  • Roles and permissions: Important for project leaders and administrators. Make sure that all users responsible for reviewing and approving Work Items have the necessary role assignments with the necessary permissions.

  • Workflow Configuration: Important for administrators and project leaders. Others may find the information useful to better understand underlying concepts, but it is not essential in order to find and approve the Work Items you are responsible for reviewing.

  • Approvals Interface: Important for everyone involved in the approval process. You will need to familiarize yourself with approvals-related user interface features in order to find, review, and approve/disapprove the items for which you are designated as an Approver.

Roles and Permissions

There are several user permissions that provide security for approvals.

Approve Work Items: To be able to approve Work Items, users must be assigned the project role project_approver, and this role should be granted the permission named "Permission to APPROVE/DISAPPROVE".

Approve as Different User:To allow users to mark items as approved or disapproved by another user (i.e. a different user other than themselves), an administrator can grant the Work Item permission named "Permission to APPROVE/DISAPPROVE as ANOTHER USER".

Resolve Approval Comments:To be able to resolve Approval Comments, users must be granted "Permission to RESOLVE COMMENTS".

For information on user permissions, see the Administrator's Guide topic Configuring User Permissions.

Review and Configure Workflow

Your approach here will depend on whether you need to run an approval phase for a new project, or in an existing project where approvals are not configured into the workflow.

New Projects

For new projects, it is recommended to create them using one of the project templates delivered with Polarion version 2013-SR1 (or later). Workflow in these templates is pre-configured to support a formal approval process. After creating the project, you should review the workflow for each Work Item type and make sure it is OK with your process. In particular, review the Actions section of the Workflow Designer page, looking at the Actions on each row in the table (see links below).

Polarion's project templates are designed to meet the needs of a wide variety or organizations. However, if the default workflow, including workflow statuses and actions, do not meet the needs of your project you will either need to create a custom version of one of the "stock" project templates, or customize the workflows of the specific project. In this case, see these topics in the Administrator's Guide:

Existing Projects

If you have an existing project created from a project template prior to Polarion version 2013-SR1, and that project still needs to go through a formal process of approval of requirements or other types of Work Items, you may want to customize your project's workflow to include, or better support approvals by using the Approval Center feature.

The easiest approach is to create a sandbox project based on one of the new project templates, and in that project review the workflow configuration. You can then duplicate that configuration in your existing project. Be sure to edit the Actions and check for workflow conditions and functions, incorporating them "as-is", or tweaking them in your existing project. See the Administrator's Reference topic Workflow Functions, and the Administrator's Guide topic Configuring Work Item Workflow, especially the sub-topic Workflow for Approvals.

Electronic Signatures

In some industries you must meet strict regulatory requirements for traceability and be able to document when requirements were approved and by whom, ensuring that only authorized people can "sign off" on them. Your administrator can configure Polarion to support electronic approval signature that will satisfy many regulatory requirements in many industries. Be sure to check that electronic signatures for requirements approval are allowed by the body whose regulations you must meet. For information, see Administrator's Guide: Configuring Work Items: Requiring Signatures for Workflow Actions.

Note

If a Work Item that has been approved using an electronic signature is duplicated, the new Work Item will not show any indication of the source item's signature, and the new item is not approved or electronically signed. New duplicate items must be reviewed, approved, and e-signed.

Approval Center Interface

The main user interface component for reviewing and approving Work Items is the Approvals panel. In a Document, it is one of the panels available in the Document Sidebar. You can show and hide it with the Sidebar menu in the Document Editor toolbar. In the Table or Tree view of the Work Item Tracker, you can find it on the panels menu, on the toolbar next to the Query Builder. Refer to the following figure to locate the access control:

Figure 6.23. Accessing the Approvals Panel

Accessing the Approvals Panel

How to access the Approvals panel from a LiveDoc or the Tracker

The Approvals panel has two tabbed pages:

  • All Approvals: Reports statistics of the current state of all Work Items, regardless of who is designated as Approver(s). Also enables you to invite people to approve Work Items by providing a URL which you can paste into email or instant messages. When a Work Item is selected, this tab also provides a button for adding an Approval Comment, displays the names of users who are assigned to approve, have approved, and have disapproved the current item, and displays all Approval Comments for the Work Item, if any.

  • My Approvals: Reports statistics of all Work Items for which you are designated as an Approver. When a Work Item is selected, this tab also provides buttons for approving or disapproving the current item, provides another button for adding an Approval Comment to the item, displays the names of other users who are assigned as Approvers of the current item and what action each of those users has taken, and displays all Approval Comments for the Work Item, if any.

Figure 6.24. Approvals Panel Statistics

Approvals Panel Statistics

Approvals panel tabbed pages when Work Item is and is not selected

Understanding the Approval Statistics

Approval statistics are color coded in the user interface (see previous figure).

  • Outstanding - All Approvals: No user is currently designated as Approver. My Approvals: You are not currently designated as Approver.

  • Waiting - All Approvals: Waiting for approval by at least 1 user and no user has disapproved it. My Approvals: You are designated as an Approver, and the reported number of items are waiting for you to review and approve them.

  • Approved - All Approvals: The item is approved by all the currently designated Approvers. My Approvals: You are designated as an Approver, and you have approved the item.

  • Disapproved - All Approvals: The item is disapproved by at least one of the currently designated Approvers. It is reported as Disapproved until such time as the disapproval is resolved, even if one or more Approvers have approved it.

    My Approvals: You are designated as an Approver, and you have disapproved the item.

The Approvals panel statistics are for the current context... Document or project.

Approvers are normally designated automatically by the workflow engine on the basis of some role ('project_approver', for example), or an explicit list specified in the workflow configuration. The list of designated Approvers appears in the Approvers field of a Work Item when viewed in the Table view. It is possible to add Approvers to the list manually.

Using Approval Center Features

The topics in this section focus on tasks involved in the default approval process (as configured in Polarion's project templates), and explain how to access and use the relevant Approval Center features. Unless specifically noted otherwise, the information pertains to Work Items contained in a LiveDoc document and to Work Items contained in the Work Item Tracker (Navigation > Work Items).

Reviewing Current Approvals

To review the current state of approvals:

  1. Open the Approvals panel for the context you want to review (Document or project tracker), and select the All Approvals tab.

  2. If reviewing in a Document, do not select any Work Item. If reviewing Document-based items in the Table or Tree view of the Tracker, select any Heading item.

The Approvals panel shows a statistics summarizing the overall status of approvals, reporting counts for items Outstanding, Waiting, Approved, and Disapproved. See topic Understanding the Approval Statistics for more information.

If Work Items are not contained the Work Item Tracker, one Work Item is always selected, so you cannot see the Approval in its state when no item is selected. You can, however, still see the overall approval statistics in the Approvals panel.

Inviting Approvers

Approvers designated for a Work Item are listed in the Approving Users table of the Approvers field of Work Items. You can view the list in the Table or Tree view of Work Items. Ideally, Approvers should be automatically designated via the workflow, as discussed earlier in this chapter. It is also possible to add Approvers by manually editing the Approvals field. Either way, when a user is designated as an Approver the system automatically sends him/her an email notification.

In an ideal world, all Approvers will respond to the automated email notification and log in to review the Work Items they must approve. However, in reality, many people set up rules in their email clients that file or even ignore Polarion-generated notification emails, or they simply don't read notification emails. For this reason the Approval Center provides the Invite for Approval feature. When a set of Work Items in a project is ready for approval review, the project leader or other team member can use the feature to copy a URL that links to the items to be reviewed and approved. This URL can be pasted into emails or instant messages created by the team member inviting people to approve the waiting Work Items. These will usually get more attention than system-generated communications.

To explicitly invite Approvers:

  1. Open a Document containing the Work Items that are ready for approval review, or open the Work Items topic of a project containing tracker-based Work Items that are ready for approval review.

  2. Open the Approvals panel and select the All Approvals tab.

  3. Click the Invite for Approval button.

  4. In the Invite for Approval dialog, copy the URL displayed there to your computer's clipboard.

  5. Create email messages or instant messages for people who must review and approve the Work Items, pasting the URL from your clipboard into the message body along with any other text you write. For example, you might provide explicit instructions for your approval process in addition to the link.

Finding Your Items to Approve

If your job is to review and approve Work Items, the Approval Center feature provides an easy way to locate the items you need to review to approve or disapprove.

  1. Log in to your Polarion portal and open the project that has items awaiting your review.

  2. If the items are contained in a Document, open it by browsing the Documents and Pages topic in Navigation, or searching for the Document name.

    If the items are created directly in the Work Item Tracker, click on Work Items in Navigation to open the Table view of project Work Items. You may want to expand Work Items to show the types that exist in your project, and click a Work Item type to filter the table for that type. For example, if you will be reviewing Requirements, expand Work Items and click on Requirements.

  3. Open the Approvals panel and select the My Approvals tab.

  4. If there are any items awaiting your approval, the tab shows a number grater than zero in the Waiting state. Click the drop-down control for Waiting, and on the menu choose Open Filtered Document (if working in a Document), or Open Filtered Table (if working in the Tracker's Table view).

After following these steps, a new browser tab opens that displays the Document or the Table filtered to show only the Work Items awaiting your approval. This means that these items list you as an Approving User in their Approvals field, and the items are in the Waiting approval state, meaning you have not yet marked them as approved or disapproved. You can now proceed to review and mark items in this browser tab.

TIP

The default configuration of your My Polarion page lists items awaiting your approval.

Querying for Approval Items

In the Table view of Work Items, you can use the Query Builder to query for items with a specific approval state, and/or with specific users designated as Approvers.

You can query for a specific approval state selecting the Approval State field as a visual query element, and selecting the value(s) to query for. For example, to query for disapproved items, select Approval State in the fields panel, and then select Disapproved in the values panel.

You can query for items having one or more specific users designated as an Approving User. Create a visual query element and select Approvals in the fields panel, and then the name(s) of the approving user(s) in the fields panel. You can query for items where you are designated as an Approver by selecting Me in the fields panel.

For more information on using the Query Builder, see the User Guide topic Searching Work Items.

Approving/Disapproving Work Items

Assuming you are looking at the items you need to review for approval in the filtered Document or Table (as described in the previous section), you can now mark the items as approved or disapproved. You can mark items individually, or mark multiple items all at once.

Marking a Single Work Item

To mark a single Work Item as approved/disapproved:

  1. Be sure you are working in the filtered Document or Table and have selected the My Approvals tab in the Approvals panel.

  2. If working in a Document, select the Work Item you want to approve or disapprove. If working in the Tracker, select the item in the table.

  3. In the Approvals panel, click the Approve button or the Disapprove button, depending on your decision.

  4. Repeat the previous 2 steps for other single Work Items in the Document or Table.

  5. If working in a Document, save it to complete your review and log the approvals/disapprovals.

    If working in the Table view, click the Save Approvals button in the Approvals panel to complete your review and log the approvals/disapprovals.

NOTES:

  • As soon as you mark any item using Approve or Disapprove, a link named Revert approval state change(s) appears beneath the buttons in the Approvals panel. You can click it to revert the approve/disapprove action on each single item you have marked, or you can select multiple items and use the link to revert the approve/disapprove actions on all of them at once.

  • When you mark an item with Disapprove, a new Approval Comment is automatically created in the Approvals panel. It is recommended that you enter a comment before you save your changes.

  • Your user profile must contain a role assignment that is granted the permission to approve Work Items. If you do not have this permission, you will see a message when you try to approve or disapprove items. Contact your project leader or portal administrator to resolve permissions issues.

Marking Multiple Work Items

In some cases, marking items approved/disapproved one at a time is too time-consuming. For example, suppose you review a specification document that has 50 Work Items in a Functional Requirements section, and you decide all of them can be approved. You can mark all, or any portion of the requirement items in that section as approved in a single operation.

As with single Work Items, you should be looking at the items you need to review for approval in the filtered Document or Table, as previously described.

To approve/disapprove multiple Work Items all at once:

  1. Be sure you are working in the filtered Document or Table and have selected the My Approvals tab in the Approvals panel.

  2. If working in a Document, select all the Work Items you want to approve or disapprove. Note that the selection must be contiguous... you cannot skip some item(s) in between.

    If working in the Tracker, select all the items you want to approve or disapprove in the table using the check boxes on each row, as you would for Bulk Edit. The selected items need not be contiguous in the table. Alternatively, you can modify the query to display just the items you want to mark, and select them all using the check box on the table header.

  3. In the Approvals panel, click the Approve button or the Disapprove button, depending on your decision about all the selected items.

  4. If working in a Document, save it to complete your review and log the approvals/disapprovals.

    If working in the Table view, click the Save Approvals button in the Approvals panel to complete your review and log the approvals/disapprovals.

NOTES:

  • As soon as you mark any item using Approve or Disapprove, a link named Revert approval state change(s) appears beneath the buttons in the Approvals panel. You can click it to revert the approve/disapprove actions on all the selected items.

  • When disapprove multiple selected items, a new Approval Comment is automatically created in the Approvals panel, and you must enter a comment before you can save your changes. The Approval Comment will be applied to all the disapproved items.

  • In a Document, if there is, for example, one item to be disapproved in between multiple items to be approved, you will need to do multiple select-and-approve actions, selecting and approving all items before, and then all items after the disapproved item.

  • Your user profile must contain a role assignment that is granted the permission to approve Work Items. If you do not have this permission, you will see a message when you try to approve or disapprove items. Contact your project leader or portal administrator to resolve permissions issues.

Working with Approval Comments

The Approval Center feature tags Work Item comments to identify them as Approval Comments. The following are useful points to know about Approval Comments:

  • Approval Comments can be added to a Work Item at any time during the approval review process.

  • Any user with the correct permissions can reply to an Approval Comment, and replies may have replies, creating a comment thread.

  • A user with the correct permissions can mark Approval Comments as Resolved. Resolved comments are hidden, but can be shown to any user who wants to see them.

  • An Approval Comment is automatically created when a single item or a group of items is marked as disapproved. While not required, it is generally good practice to fill it in.

  • Approval Comments are regular Work Item comments, stored in the Comments field of Work Items, but are labeled as Approval Comments in the UI.

Adding an Approval Comment

The Approvals panel displays a button for adding an Approval Comment when a Work Item or group of Work Items is selected. If multiple Work Items are selected, the comment is added to all of the selected items.

To add a new Approval Comment:

  1. Select one or more Work Items in a Document or the Work Items Table.

  2. In the Approvals panel, click the Add Comment button. A new empty comment appears in the panel.

  3. Fill in the text of the comment.

  4. Save the Document or, if working in the Table view, save the Approvals.

TIP

You can also use the (Add Approval Comment) icon that appears in the Document margin next to each Work Item, and on the row of each Work Item in the Table view.

Figure 6.25. Approval Comment Options

Approval Comment Options

Different ways to add and Approval Comment to a Work Item

Replying to an Approval Comment

To reply to an Approval Comment:

  1. In the Approvals panel, hover your pointer over the comment. Two icons and labels appear in the comment.

  2. Click on Reply. A new reply comment appears in the panel.

  3. Fill in the text of the reply.

  4. Save the Document or, if working in the Table view, save the Approvals.

Figure 6.26. Approval Comment Reply

Approval Comment Reply

Hover over Approval Comments to reply to them

TIP

You can also reply to an existing Approval Comment using the Comments section of the Work Item form in the Work Items Table view.

Resolving Approval Comments

When the approval discussion is complete, it can be useful to mark the Approval Comments as Resolved. This is especially true for items that were initially disapproved. These will always have one comment, and often with have some back and forth discussion until the item is revised to resolve the issues that resulted in disapproval. Once the issues are addressed, marking the existing comments as Resolved hides them. The item can then go through the review and approval process again without the distraction of the original Approval Comments. Any user who needs to see the original discussion can unhide the resolved Approval Comments.

To resolve an Approval Comment:

  1. Show the Approvals panel if it is not displayed.

  2. Select the Work Item containing the Approval Comment.

  3. Hover your pointer over the Approval Comment you want to resolve. If the comment is in a thread, select the top-level comment in the thread.

  4. Click Resolve. The Approval Comment and all replies are shaded.

  5. Save the Document or, if working in the Table view, save the Approvals. The Approval Comment and all replies are hidden.

Figure 6.27. Approval Comment Reply

Approval Comment Reply

Hover over an Approval Comment to resolve the entire thread

Viewing Resolved Comments

There are 2 ways you can show resolved Approval Comments, which are hidden by default when you access the Work Item they belong to:

  • In the Approvals panel header, click the (Pane Settings) icon and check the Show Resolved Comments box.

    Resolved comments appear shaded in the Approvals panel when shown.

  • In the Table view of Work Items, scroll to the Comments section of the form and check Show Resolved Comments.

Figure 6.28. Unhiding Resolved Comments

Unhiding Resolved Comments

How to reveal hidden resolved Approval Comments

Reopening Resolved Approval Comments

It may be necessary to reopen some discussion thread around approval/disapproval of some Work Item. To reopen a resolved Approval Comment, you must first show resolved comments (see Viewing Resolved Comments). Once you are seeing resolved Approval Comments, there are 2 ways you can reopen one:

  • In the Approvals panel, hover over the Approval Comment you want to reopen and click Reopen.

  • Reply to an Approval Comment in the Approvals panel, or any reply in its comment thread.

Resetting the Approval State

Some Work Items are inevitably rejected (disapproved) during the initial phase of the approval process. The items may undergo discussion in Approval Comments and other means, and eventually the items are revised. After revision, they must undergo another review and be approved, or rejected again. The situation can arise where you have revised items that were initially disapproved and are ready to be reviewed again, but are still marked as disapproved. For these items you can reset the approval from the Disapproved state to the Waiting state.

To reset the approval state of a Work Item:

  1. Select the Work Item in its containing Document, or the Table view of Work Items.

  2. Open the Approvals panel and select the All Approvals tab.

  3. Under the Add Comment button you will see the label Disapproved by: followed by the names of Approvers who disapproved the item. Click the 'X' icon associated with this label and the names (you will see a tooltip "Reset approvals to the Waiting state").

  4. Save the Document, or if working in the Table view, click the Save Approvals button.

TIP

You can reset the approval state of several Work Items at once. In Step 1 above, simply select multiple Work Items.

If working in a Document, select contiguous items by dragging over them to highlight them. In the Table or Tree view, check the box on the row of all the items you want to reset at once. (They need not be contiguous in the listing.)

Sign Work Items

This section details how signatures work when approving a Work Item or changing its workflow status.

See the Sign documents and Approval sections for additional information on how signatures and the approval process works and how to enable and configure them.

Work Item Approval Signatures

When a Work Item is approved, the name of the user that approved it, the date and the approval verdict all appear in the comment section of the Work Item.

Approve and Sign an Work Item

When signing and approving a Work Item:

  • Users with sufficient rights can Approve a Work item "On behalf of" the assigned approver.

    (For example, if the assigned approver is on holidays but the item needs to be approved before they get back.)

  • Likewise the designated approver can "Disapprove" any approval made on their behalf.

  • Polarion supports up to 20 approvals per Work Item.

In the example below, a system administrator is approving the Work Item on behalf of Ckohli, but upon his return Ckohli decides that the Work Item is not ready to be approved and reverses the decision.

  1. Open the target Work Item.

  2. Scroll to the Approvals section and click in the approvals heading.

  3. Select the State beside the target approver.

    If you have sufficient rights, and want to add another approver, select them in the drop-down list on the left and click on the right.

  4. Change the approval State and click Save.

  5. An approval comment containing the date, the user that approved it and the approval verdict appears in the Comments section of the Work Item.

Now let's say that Ckohli returns from holidays and decides that the item approved on his behalf is not actually ready to be approved.

Change the Approval State
  1. Scroll to the Approvals section and click in the approvals heading.

  2. Select the State you'd like to change it to beside your username.

  3. Click Save.

  4. Enter your Username in the e-signature confirmation dialog and click Next.

  5. Enter your password and click Sign.

  6. The original approval comment will disappear and be replaced by the updated date, user, and approval state information.

Work Item Approval and Workflow Change Traceability

Obsolete approval states are removed from the Comments section of the Work Item, but the entire approval process is still be visible in the Work Item's History .

Sign a Work Item Workflow Status Change

You can require users to electronically sign a Work Item when changing the workflow status.

The latest workflow change will appear in the Workflow Signatures section of the Work Item. Administrator's can configure the section by adding functions and conditions so that, for example, if a workflow status is reversed, all signatures that Reviewed and Approved a Reopened Work Item will disappear from this section. (They will always be tracked in the Work Item's History.)

Note:

  1. Open the target Work Item.

  2. Select the Status you'd like to change the Work Item to in the drop-down list.

    Note:

    If you haven't approved the Work Item in the Approvals section, the Perform action Approve status will be greyed out.

  3. Click Save.

  4. Click Save again on the Confirm Save dialog.

  5. Enter your Username in the signature confirmation dialog and click Next.

  6. Enter your password and click Sign.

  7. The status will change and an entry will appear in the Workflow Signatures section of the Work Item.

Note:

  • Polarion supports up to 20 Workflow Signatures.

  • The available workflow states will vary depending on your configuration.

  • The number of signatures that appear in the Workflow Signatures section also depends on your workflow condition and function configuration.