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.

A review request can also arrive before a connector is used. With “Confirm before connecting” set on a connector, the run stops before an agent uses that connector and a review request is raised (a connection confirmation, in a workflow or in a cycle). It can only be approved or rejected, and its deadline is handled differently from a review step (Connection Guide).

When the step before the review step has “Values and file roles passed to the next step”, the review request screen also shows the values and files returned. You can see what will be handed to the next step before you decide.

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. When advancing, you can also edit the output of the step before and then proceed (a later section)
  • 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. When advancing, you can also edit the output of the step before and then proceed (a later section)

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 report” 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).

Editing the output before proceeding​

On either kind of review step, review or manual work, pressing “Edit output and proceed” on the review request screen opens the output of the step before in an edit box. The edited text is passed to the next step. The original output stays too, and the execution record shows both “Edited at review” and “Original output”. Up to 20,000 characters can be edited.

It appears only when the step before the review step has one output. It does not appear after a step where two or more agents ran with “Run at the same time”, after lanes join, on a review raised from a failure, or on a connection confirmation (with “Run at the same time” and only one agent, it does appear). It can also be done from the external API: for a review request whose gate.editableOutput is not null when you get it, send the corrected text (up to 20,000 characters, not counting leading and trailing whitespace) as editedOutput in a proceed decision, together with gate.contextVersion when it is not null (external API documentation).

Only the people you name, and their delegates, can decide​

Only those named as reviewers, and their delegates during the delegation period, can decide (Who decides what). This is separate from a role: even an owner cannot decide unless they are named as a reviewer on that step (or are a reviewer's delegate). 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 and a connection confirmation review request, however, as a rule have every owner at that moment as their 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.

Owners, operators and people with the organization operations role can reassign the reviewers of review requests not yet decided. Use it when a reviewer is away, for example. For each workflow run, it replaces the reviewers of that run's undecided review requests, all of them, with the members you choose. Only the people who newly became reviewers get the review-request notification. The reviewers set on the step do not change. Review requests raised after that go to the reviewers named on the step. The Records (audit trail) keep “Approvers reassigned” (one per review request) and “Run approvers reassigned” (one per run).

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”. Reviewers are reassigned with “Reassign approvers” on the screen of the workflow run opened from “Action needed”, or with the “Reassign approvers” bulk action in “Action needed” (Record Guide)

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.

The reviewers and their delegates, and also owners, operators and people with the organization operations role, can later extend the deadline of a review request not yet decided (only the reviewers and their delegates decide, as before). Use the “Extend deadline” bulk action in “Action needed” and enter the new deadline (a date and time later than now) (Record Guide). The overdue mark is cleared, and it waits for the extended deadline. It is not bound by the review deadline limit (720 hours). Extending it does not change the expiry of the link in the notification email (once the link expires, a reviewer or delegate can still decide on screen). The Records (audit trail) keep it as “Confirmation deadline extended”. The deadline of a connection confirmation cannot be extended.

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 and their delegates can.

You can also settle a default contact for the project. Choose one person under “Default contact when overdue” on the Settings tab, and review requests with no escalation contact on their step (including those raised from the result of a “Run by Agent” step) reach that person. Where the step names a contact, that one is used. Either way, it reaches the person only if they are a member when the review request is raised.

It arrives under “Notify and keep waiting” (of the reminders before the deadline, only the second one, when little time is left, also reaches the contact, by a share link). 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”. The default contact is under the Settings tab > “Triggers and notifications” > “Notifications” > “Default contact when overdue” (only an owner of a workflow can change it)

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 parallel 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 can carry up to 5 files from the project library (not for a connection confirmation). 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. An external automation step can also be chosen as the step to go back to (a send-back sends it again). Where there are parallel 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.

On a review request after the join, a reviewer deciding it can also choose an agent step in each lane before the join. Such a step is marked “Redo only (lane name), then wait for all lanes again”. Choose it, and only that lane redoes from that step; the other lanes keep the results they finished with and wait at the join. The default step to go back to, an automatic send-back at the deadline and a bulk send-back from “Action needed” still go back to a step on the same side (after the join), as before.

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 closes the run there. The decision itself cannot be undone. A run closed by a rejection or a failure can, however, be continued by owners, operators and people with the organization operations role from a chosen step, as the same run (next section). To start over from the beginning, start a new run.

Where on screen “Inbox” on the left > “Review requests” > 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” > “Default send-back step”. 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)

Resuming a closed run​

A workflow run closed by a rejection or a failure can be continued by owners, operators and people with the organization operations role from a chosen step, as the same run. The failure can be that of an agent step or of an external automation step. A cancelled run cannot be resumed. To do it again, start a new run.

Press “Resume” and a screen shows why it closed and lets you choose the step to resume from. The reason shows as “Rejected at the confirmation in “(step name)”” or “Failed at “(step name)””, with the reason for the rejection where it was rejected.

  • Step to resume from — chosen from the agent steps and external automation steps up to the step that caused the close, on the same side of it (the same lane; outside the lanes, before the split or after the join). The default is that step if it is an agent step or an external automation step, or the nearest such step before it if it is a review step. Where there is no agent step to go back to, the run cannot be resumed
  • Reason for resuming — required (up to 1000 characters). The reason is shown on the rows of the steps that run again because of the resume. The Records (audit trail) keep that the run was resumed, but not the reason

Resuming runs again from the chosen step onwards, and keeps the earlier results. The order of the steps and the placements stay as they were when the run started. When you resume from a step inside a lane, the other lanes that had reached the join keep their results and wait at the join, and the other lanes that were stopped when the run closed start again from the step where they stopped. The rejected review request is not reopened. If the run reaches a later review step, a new review request is raised. The rows of the steps that run again because of the resume (including rows in other lanes that run again) show “Resumed: (reason)”.

It cannot be resumed while the project is paused, while an admin has stopped the project, while the number in progress is at its limit (resumed runs count too; see the Trigger Guide), or when someone else's action has changed the run's state.

The Records (audit trail) keep it as “Run resumed”.

Where on screen Workflow history tab > “Resume” on a run closed by a rejection or a failure (shown to owners, operators and people with the organization operations role; not shown while an admin has stopped the project) > “Resume this run”, with “Step to resume from” and “Reason for resuming”

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, and their delegates, 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
  • Thinking a rejected run can never be continued. A run closed by a rejection or a failure can be resumed by owners, operators and people with the organization operations role from a chosen step. The rejected review request itself is not reopened