Skip to main content

Review Guide

This guide covers the settings for putting a person's decision part-way through the work: where to place a review, who to let decide, and what to do about deadlines.

What a review step is for is covered in Human review. How to divide the work into steps is covered in the Design Guide.

Where a section has a place on screen, you will find where to set or check what it asks you to decide at the end of it. Steps are configured on the screen you reach through Edit at the top of the project screen (shown to owners only).

What a review step settles is whether the work goes on​

A review step is where a person decides whether the work may go on to the next step. When a run reaches a review step, it stops there. From then on it proceeds either on the reviewer's decision or on the setting for what happens once the deadline passes.

It is not a mechanism for stopping what an agent does. A review step stands between two steps, so whatever the previous step already did is not undone. Where there is an operation you do not want carried out, forbid it in the execution rules rather than reviewing it (Execution Rules Guide).

Review steps belong to workflows. A cycle cannot have one. But a cycle can still bring a person in; what differs is how. A workflow holds the run itself at a step; a cycle holds one subject at a time and carries on with the rest of the rounds. How to do it in a cycle is covered in the Design Guide. What this guide covers is the review step of a workflow.

Where on screen Edit ＞ “Editing tools” on the left ＞ “Add step” ＞ “Human check”, or “+” between steps in the diagram in the middle ＞ “Human review”, to add one. Select it in the diagram in the middle and its settings appear on the right

A review, or manual work​

There are two kinds of review step. What the person does in the meantime differs.

  • Review (a person judges the Agent's result) — they look at the output of the step before and decide whether to advance it, send it back, or reject it. In a workflow handling incoming applications, this is the reviewer looking at what the agent checked and approving it
  • Manual work (AI does not run; a person does the work, then proceeds) — no agent runs on that step. A person finishes the work themselves, then advances it. Use it where you want work you are not delegating to an agent — registering something in another internal system, say — built into the flow

The “What to review” tab of a review request lists the output of every agent on the last step where agents ran, and the files they produced (under “Agent summary” and “Deliverables”). On a review step right after lanes join, it lists what came from the last agent step in each lane. The reviewer decides from these. Pressing a deliverable’s name opens a preview, where it can also be downloaded. The project, the current step, the next step, the requester and the reviewers are on the “Related info” tab, and the course of the request is on the “Activity” tab.

No agent can be placed on either kind. Where there is work to be placed, divide the steps either side of it.

The kind is a separate setting from how it waits. Even manual work is handled automatically once the deadline passes, according to the setting in the next section. Where you need it held until a person has finished the work, settle the combination of waiting settings as well (the next two sections).

Only the people you name can decide​

Only those named as reviewers can decide. This is separate from a role: even an owner cannot decide unless they are named as a reviewer on that step. An owner who is not named can still see the review request. A review request raised from the result of a “Run by Agent” step, however, as a rule has every owner at that moment as its reviewers (Design Guide). On a review step too, if every named reviewer has been removed from the members by the time the review request is raised, every owner at that moment becomes its reviewer.

The candidates are the project's members. Someone who is not a member cannot be made a reviewer, so add whoever you want deciding as a member first. Remove them from the members and they are taken off the reviewers too, so they can no longer decide (they are also taken off as the escalation contact) (Who decides what).

You can name several people. The first decision is final, though. This is not a mechanism for gathering everyone's agreement, so where a joint decision is needed, settle it elsewhere — in a meeting, say — and have one person answer on behalf of the rest.

Where an enabled review step has no reviewers named, the run cannot be started. The same goes for a step left with no reviewers after members were removed. Steps you disabled are left out of the check. You can check for this with “Check settings” before applying.

Where on screen Edit ＞ select the review step in the diagram in the middle, then “Check settings” on the right ＞ “Basic settings” ＞ “Kind of review”, “Reviewers”. Members are added under the Settings tab ＞ “Members”

Waiting, or proceeding at the deadline​

Review method offers two. This is what changes what a review step means.

  • Stop and wait for a decision — it stops until the reviewer decides. What happens once the deadline passes follows the setting in the next section
  • Notify and proceed after the deadline — the reviewer can decide up to the deadline, but once it passes, it advances to the next step automatically (on the final step, the run is completed)

The criterion is whether it may go on if nothing has been decided. If it may, choose "Notify and proceed after the deadline"; if it may not, choose "Stop and wait for a decision".

Where you must have a person's answer, combine "Stop and wait for a decision" with "Notify and keep waiting". Anything else is processed automatically, without a person, once the deadline passes.

Anything that advanced at the deadline was not approved. The record shows that it was processed at the deadline rather than decided by a person. It is not counted under “Approved by people”, but it does go into “Typical wait” (Records and metrics).

A review always has a deadline. You give it in hours, and leaving it empty uses the default (for the value, see the Settings reference). A review with no deadline cannot be created.

Settle the deadline, and what happens once it passes, together with the volume of requests. The effect on starting runs is in the Trigger Guide.

What happens once the deadline passes​

Only where you chose "Stop and wait for a decision" can you choose from four things to happen after the deadline.

  • Notify and keep waiting — it only reports that the deadline passed, and a reviewer's answer is still accepted afterwards
  • Proceed automatically — it advances to the next step (on the final step, the run is completed)
  • Send back automatically — it is redone from the step you send it back to
  • Reject automatically — that run is closed

The default is "Notify and keep waiting". Take it that stopping and waiting for a person is the default behaviour.

Where you chose "Notify and proceed after the deadline", this setting has no effect, and the screen will not let you choose it either. You have already said what happens once the deadline passes.

A review step with “Destination options” is not decided automatically after the deadline either. “When the deadline passes” cannot be chosen; it reports that the deadline passed and waits until the reviewer chooses a destination. It cannot be combined with “Notify and proceed after the deadline”.

"Send back automatically" and "Reject automatically" move the work on without anyone looking at it. Before choosing either, make sure that the step it goes back to can be redone without harm, and that closing it causes no trouble.

A passed deadline can also be told to someone other than the reviewers. Name one member as the escalation contact when overdue and it reaches them as well as the reviewers. That person cannot decide. Only the reviewers can.

It arrives under “Notify and keep waiting”. Under the settings that proceed, send back or reject automatically, the contact hears nothing so long as that goes through.

Where on screen Edit ＞ select the review step in the diagram in the middle, then “Check settings” on the right ＞ “Basic settings” ＞ “Review method”, “Deadline (hours)”, “When the deadline passes”, “Escalation contact when overdue”

What happens after the decision​

The reviewer has three to choose from, and what follows differs.

  • Proceed to the next step — the next step runs. On the final step, the run is completed (and the wording on screen differs there)
  • Send back — the agent redoes the work from the step you choose
  • Reject — that run is closed. The agent does not redo anything

Put “Destination options” on a review step and, instead of “Proceed to the next step”, the reviewer proceeds by choosing a destination. The options are 2 to 5 later steps, each given a display name in advance. Where there are lanes, the options are also chosen from the same lane as the review step (outside the lanes, from the same side of the split — before it, or after the join). The reviewer picks one under “Choose a destination” and presses “Proceed to the chosen destination”. The steps before the chosen destination are not run (the run record shows them as “Not selected in the branch”). Only the options that are enabled steps when the run starts are used. Where fewer than two of them are enabled, that review does not ask for a destination and proceeds as usual.

A send-back and a rejection both need a reason. Only advancing it lets you leave one out. A send-back also needs the step to go back to. The reason for a send-back is passed to the agent and kept in the record — write what you want put right.

Only enabled agent steps before this review step can be chosen to go back to. You cannot go back to a review step or one you disabled. Settle a default per step and it is used when the decision is made, provided it lies before this review step. A review request raised from the result of a “Run by Agent” step can also go back to that step itself. It is marked “Redo this step” and, provided it has not reached the send-back limit, is the default. Where there are lanes, the step to go back to is also chosen from the same lane as the review step (outside the lanes, from the same side of the split — before it, or after the join). Where there is no step to go back to, “There is no step to send back to” is shown and the request cannot be sent back.

There is a limit on how many times a run can be sent back to the same step. Within one run, a step can be sent back to three times by default. Both reviewers' send-backs and automatic send-backs at the deadline count. The review request shows “Sent back ◯/◯” for each step to go back to, and a step that has reached the limit cannot be chosen. Once every step has reached the limit, proceed or reject instead. Where an automatic send-back at the deadline hits the limit, the request stays undecided and waits for a reviewer.

Where the step you go back to holds no agent, it is skipped and the run moves on. Make sure the step you want redone has an agent on it.

A rejection cannot be undone. The run closes there, and it cannot be resumed later. To do it again, start a new run.

Where on screen “Review requests” on the left ＞ pick one ＞ the decision buttons (the wording differs on the final step). The default step to go back to is under Edit ＞ select the review step in the diagram in the middle, then “Check settings” on the right ＞ “Basic settings” ＞ “Send back to”. Destination options are under Edit ＞ select the review step in the diagram in the middle, then “Check settings” on the right ＞ “Basic settings” ＞ “Use destination options”. The send-back limit is under the Settings tab ＞ “Execution rules” ＞ “Execution” ＞ “Send-back limit (per target step)” (a change applies to runs started afterwards)

Distinctions worth keeping straight​

These are the distinctions that cut across the sections above.

  • Thinking a review step stops an operation. A review step stands between two steps, so whatever the previous step already did is not undone. Forbid an operation you want stopped in the execution rules (Execution Rules Guide)
  • Counting an automatic action at the deadline as a person's decision. Anything that advanced under "Notify and proceed after the deadline" had no answer from a reviewer. It is not counted under “Approved by people”, but it does go into “Typical wait”. What was sent back or rejected automatically, on the other hand, does go into “Send-backs, rejections, cancellations” (Records and metrics)
  • Laying out the steps on the basis that "we can ask someone later". An agent does not wait for a person to answer part-way through a run. In a workflow, put what you want a person to decide on as a review step. A cycle cannot have one, so there you hold that one subject for a person's decision instead (Design Guide)
  • Thinking an owner can decide. Only those named as reviewers can. The role alone is not enough (only a review request raised from the result of a “Run by Agent” step has, as a rule, every owner as its reviewers)
  • Thinking that naming several people gathers their agreement. The first decision is final. It does not wait for everyone