Overview

Gathering consensus is a core part of collaborative engineering. Verve provides a streamlined process for capturing and maintaining consensus in fast-moving developments, called Verve Review. Teams use Verve Review to collect feedback during the earliest of design capture stages.

This is broken into two user personas: the “creator” and the “reviewer.” The creator creates items, organizes them as appropriate, and then sends out requests for approval. The reviewer provides their feedback in the form of an “approved”, “abstained”, or “rejected” option.

Our example uses the “sandwiches” systems engineering example preload, available as an importable CSV from Prewitt Ridge.

Data Model

The Approval process creates a ItemApproval object in the Verve database. A single ItemApproval object creates a relationship between a single Item and a single User. A User cannot have duplicate ItemApproval objects for the same Item, and an Item cannot have duplicate ItemApproval objects for the same User. However, a User may have many ItemApproval objects for different Items, and an Item may have many ItemApproval objects for different Users.

This ItemApproval object maintains a State value, which can be any one of the following:

  • draft

  • requested

  • approved

  • rejected

  • abstained

This then impacts both the Review mode’s sidecar and the Item Status

ItemApproval State

Review Mode sidecar

Item Status impact

Draft

Not present

No effect

Requested

Present for user, requests Approve, Reject, Abstain

Yellow - in progress

Approved

Indicates “approved”

Supports green

Rejected

Indicates “rejected”

Forces red, regardless of other statuses

Abstained

Indicates “abstained”

No effect

Requesting a Review

To begin requesting a review, navigate to a Group.

(While any item can have an arbitrary number of review objects, the ability to request approvals via the web interface is limited to a Group. We currently prevent a user from requesting ALL items in the Default View.)

Engineer selects the “group” dropdown and hovers over the “L2 Requirements” group

This enables the “SEND FOR REVIEW” button, present in the subheader.

From there, the engineer may add any number of users to review the item.

Once all the users are added, click “SEND FOR REVIEW”

These users will then be notified of their review request upon next log-in.

Reviewing Items

When an engineer has items to review, this is indicated within Verve by a red badge next to the Review item in the navigation menu.

The user can then use the Default view to scroll through all items to provide their feedback, or they can go to the specific Group that contains the items in question. This is indicated by a red badge on the Group icon, as follows:

From here, the user can then indicate their feedback on each item accordingly.

Upon completion, the red indicator badge goes away until the next set of reviews is requested..

Automatic re-request

If an engineer tries to change an item after it’s been reviewed & approved, Verve informs the engineer that their action will invalidate the review.

If the engineer decides to continue, Verve automatically invalidates all approvals associated with that item. All previously-requested approvals will then be reset to “draft” status, and the relevant engineers will see a Review Requested indicator badge on the Review menu item when they next log in.

Manual re-request

After an item’s review is rejected, if an engineer updates that item, Verve offers the engineer a Refresh Reviews icon button.

  • Clicking refresh icon updates the any rejected requests from “rejected” back to “requested” so requested user is notified to re-review item

  • DOES NOT revert previous “approved” reviews by other users (question)

  • DOES modify existing “requested” reviews to update the request date to be more recent, thus moving the review higher on the user’s “Pending Reviews” section.

API Access

Advanced users can manipulate approvals via the API. Since Approvals act upon an Item, developers should familiarize themselves with the Item API. When familiar with those concepts, developers should progress to the Approval API.