Appearance
Reviews and Approvals
Table of Contents
Reviews and approvals control when critical changes take effect. A review records a person's feedback on a change. An approval is a review that counts toward the requirements for releasing that change.
Factorial requires approvals before a procedure revision can be released and before a work order redline can be applied. The model follows the pull request reviews familiar from software development: reviewers approve, request changes, or comment, and release is allowed only when enough of the right people have approved and no one who can approve has outstanding change requests.
Review Policies
A review policy defines how many approvals a type of change requires. Each organization has one policy per reviewable type, and the procedure policy requires one approval by default.
Review policies apply to the entire organization and are read at the moment Factorial checks them. Changing the required number of approvals immediately affects every procedure revision that is already in review.
The required number of approvals may be zero. A policy of zero allows a revision to be released without approvals, but outstanding change requests still block release.
Only administrators can change review policies. Every change is kept as part of the policy's history, including who made it and when. See Organization Settings.
Factorial does not provide a way to bypass a review policy. An administrator who needs to release without the usual approvals must change the policy itself, which applies to every revision in review.
Who Can Approve
Anyone in the organization may review a procedure revision. Only reviews from users who hold the Approve procedure permission count toward the policy or block release.
The permission is evaluated using each reviewer's current roles, not the roles they held when they submitted the review. Removing the permission from a user, deactivating one of their roles, or deactivating the user immediately removes the effect of their reviews. Restoring the permission restores it. This keeps the release decision consistent with the organization's current access rules.
Authors cannot approve their own work. For a procedure revision, the authors are:
- The procedure owner
- The user who submitted the revision for review
Authors may comment on the revision but cannot approve it or request changes. For the same reason, the procedure owner and the procedure's tags can only be changed while the revision is in Draft.
A change request is not cleared when its reviewer becomes an author, either by becoming the procedure owner or by submitting the revision for review. An author with an outstanding change request may approve the revision to withdraw that request. The approval does not count toward the review policy.
Submitting Reviews
Each review has one of three outcomes:
- Approve indicates that the reviewer accepts the revision.
- Request changes indicates that the revision must change before it is released.
- Comment adds to the discussion without affecting release.
Approve and Request changes are accepted only while the revision is In review. Anyone may Comment at any status, including on a draft that has never been submitted. Those comments are grouped under Before review until the first submission. On the procedure page, an outcome you cannot submit is shown disabled and says why.
An approval or change request may include a written explanation. A comment always includes one. Reviews may mention other users, who are notified.
Reviews are the discussion for a procedure revision. Procedures do not have separate general-purpose comments.
Reviews are never deleted. The author of a comment may edit or delete it while the revision is a draft or In review, because a comment is discussion rather than a decision. Once the revision is released or archived, its comments are fixed along with the rest of its review history.
The written explanation attached to an approval, a change request, or a submission note can only be edited or deleted while its review cycle is open, which means the revision is still In review and has not been resubmitted. Once the cycle closes, because the revision is released, archived, returned to Draft, or resubmitted, that explanation is fixed. The reason given for dismissing a review can never be edited or deleted. The review history therefore shows what each reviewer and administrator wrote at the time of the decision. A deleted explanation is shown as deleted, while the review outcome remains part of the revision's history.
Requesting Reviews
A review request asks a specific person to look at a revision. Requests are advisory: they notify the reviewer and place the revision in their review center, but they never change what a revision needs in order to be released. A requested reviewer who never responds does not block anything.
Anyone may request a reviewer while the revision is in Draft or In review. Requests are usually made when submitting a revision for review.
The reviewer picker offers the people who hold the Approve procedure permission, because only their reviews count toward the policy. Selecting Show everyone offers every active user instead, and users whose reviews would not count are marked. Their perspective is often still worth asking for.
A request stays pending until that reviewer submits any review in the current review cycle, including a plain comment. If their review is later dismissed, the request becomes pending again, because the revision is waiting on that reviewer once more.
Each requested reviewer is listed with what they have done so far, and each one carries its own actions:
- Withdraw request removes the request. It is available only while the request is pending, so a reviewer who has already responded cannot be quietly dropped. Their review remains part of the discussion either way.
- Ask for another look requests the same person again after they have reviewed, which makes their request pending once more.
Requests carry across review cycles. When a revision returns to Draft and is submitted again, its requests become pending again, because the reviewers are being asked about new content. Requests are not copied to a new revision created by an uprev, in the same way that reviews are not.
Submission Notes
Each time a revision is submitted for review, Factorial records who submitted it and an optional note for the reviewers. The note opens that cycle's discussion and may mention other users, who are notified.
A note is useful for saying what changed and where reviewers should focus. Its author may edit or delete it while the cycle is open, under the same rules as review explanations. Every cycle keeps its own submission, so the discussion shows what each round of review was asked to consider.
Review Cycles
Each time a revision moves from Draft to In review, a new review cycle begins. Contents are frozen while a revision is in review, so every review within a cycle evaluates the same content.
For each reviewer, only their most recent approval or change request matters. A later comment does not replace an earlier approval or change request.
The two outcomes behave differently across cycles:
- Approvals count only in the cycle in which they were submitted. Returning a revision to Draft and submitting it again resets its approvals, because the content may have changed after it was approved.
- Change requests remain in effect across cycles until the same reviewer approves the revision or an administrator dismisses the request. Resubmitting a revision or changing its owner does not clear a change request, so a reviewer's concern cannot be bypassed by editing the revision and submitting it again.
Reviews from earlier cycles remain visible as outdated so that the full discussion stays with the revision.
Review cycles are numbered, starting at 1. A review applies to the cycle the reviewer was looking at. If the revision is resubmitted after the reviewer loaded it, Factorial rejects the review and the reviewer must reload the procedure. An approval therefore always applies to content the reviewer could see. Reviews submitted through the API must include the current review_cycle.
Release Readiness
A procedure revision is ready to release when all of the following are true:
- The revision is In review.
- The number of approvals from the current cycle meets the review policy.
- No reviewer who holds the Approve procedure permission has an outstanding change request.
Factorial calculates readiness from the current reviews, policy, and permissions each time it is displayed or checked. The procedure page shows whether the revision is ready and what remains, and Release is available only when the revision is ready. Factorial enforces the same rule when a revision is released through the API.
Dismissing Reviews
An administrator may dismiss an approval or a change request, for example when the reviewer is unavailable and the concern has been resolved another way. A reason is required.
A dismissed review no longer counts toward the policy or blocks release. It remains in the revision's history along with the administrator who dismissed it and the reason. Comments cannot be dismissed.
Dismissing a review also reopens that reviewer's review request, if they had one, and puts the revision back in their review center.
Reviews may be dismissed while a revision is in Draft or In review.
An administrator cannot dismiss reviews on a revision they own or submitted for review. This keeps the rule that authors cannot approve their own work from being bypassed by an administrator author. A change request on such a revision is resolved in one of these ways:
- The reviewer approves the revision.
- Another administrator dismisses the change request.
- An administrator removes the Approve procedure permission from the reviewer or deactivates the reviewer, for example when the reviewer has left the organization. This affects every revision the reviewer has reviewed, as described in Who Can Approve.
Notifications
Factorial notifies the people responsible for a revision as review activity occurs:
- The procedure owner and the submitter are notified of each new review.
- The reviewer, the procedure owner, and the submitter are notified when a review is dismissed.
- The procedure owner is notified when a revision becomes ready to release.
- A requested reviewer is notified when they are asked to review a revision that is already in review.
- When a revision is submitted, everyone with an active review request is notified, along with every reviewer whose change request still blocks release.
Factorial does not announce a submission to everyone who could approve it. Reviewers are notified because they were asked, or because the revision is waiting on them.
Users mentioned in a review are notified in the same way as other mentions. Factorial does not notify people of their own actions.
When a review request is withdrawn, its notification is kept but marked outdated: it is hidden from the notifications page and does not count toward the unread badge. Turn on Show outdated on the notifications page to see outdated notifications, which are labeled Outdated.
Customized Review Requirements
Work order redlines use this same review workflow, with their own Approve redline permission and review policy, and appear in the review center beside procedure revisions.
Review requirements for other entities, such as issue dispositions, issue resolutions, inventory hold releases, and task signoffs, are planned.
Planned review requirements can be added automatically by a plugin with rules about who needs to review. For example, an issue disposition could require a different set of reviewers depending on the part number and disposition selected.
Review Center
The review center collects everything in review that the person looking at it has a reason to care about. It is reached from Workspace → Review Center, and the navigation badge shows how many items someone asked them to review by name. Items they could approve without being asked are not counted in the badge. Counts above 20 are shown as 20+.
The review center has a tab for each reviewable type: Redlines and Procedures. The two are reviewed differently and offer different actions, so each has its own list. Each tab shows two counts: requested, the items someone asked the viewer to review, and can approve, the items the viewer could approve without being asked.
Within a tab, a bar of views narrows the list. Each view except Ready shows how many items it holds, and Ready shows its count while it is open. The open view says what it shows:
- Inbox lists items someone asked the viewer to review by name, and that they have not reviewed in the current cycle. The review center opens here.
- Can approve lists items no one asked the viewer about by name, but that their roles let them push through: they hold the permission to approve the item, are not an author of it, and have neither approved nor requested changes on it in the current cycle. Anyone who can approve may pick these up. An item the viewer was asked about and only commented on is listed here.
- Sent lists items the viewer sent for review: ones they opened or own, submitted, or asked someone to review.
- Ready lists items that meet their review policy and that the viewer can apply or release, or that they wrote.
- All lists everything of that type in review.
Inbox and Sent have a Show finalized toggle, off by default, that adds items that have reached their final state. On Inbox, these are requests the viewer has already answered and items they were asked about that have since closed. A request that was withdrawn is not listed. On Sent, these are the viewer's own items that were applied, released, rejected, canceled, or archived. A finalized item shows how it ended instead of its approvals.
Each list can be searched, filtered, sorted, and paged like any other list in Factorial. Both are sorted with the longest in review first by default.
Each row shows the item, where it belongs (a redline's work order or a revision's owner), how many approvals it has or whether it is ready, any outstanding change requests, who it is waiting on, and who submitted it and when.
Bulk Actions
Select items with the checkbox on each row, or select every row on the page from the header. A bar appears at the bottom of the page with the number selected, the actions, and Close and Unselect.
On the Redlines tab:
- Approve and Request changes record a review on each redline, with one comment for all of them. A comment is required to request changes.
- Reject closes each redline with one comment and one choice about the task holds.
- Apply applies each redline that is ready.
On the Procedures tab:
- Approve and Request changes work the same way on each procedure revision.
- Release releases each revision that is ready.
There is no batch: each item is reviewed, rejected, applied, or released on its own and keeps its own history, exactly as if it had been handled alone. Each button shows how many of the selected items it would act on. When it would act on none, the button is shown disabled with the reasons.
Factorial skips any selected item the user cannot act on and handles the rest. Afterwards, the review center lists every skipped item with the reason it was skipped, which is the same reason Factorial gives when acting on that item alone. Common reasons are that the user opened, owns, or submitted the item, the item was resubmitted after the page was loaded, or it does not yet have enough approvals. A bulk action handles at most 500 items.