Human Review & Approvals

Overview

Not all work should be fully autonomous.

Supervity follows a Human-in-Command model, where operators operate independently until human judgment, approval, or input is required.

Human review is not an exception or workaround — it is a first-class governance mechanism designed for real-world, enterprise-grade operations.

Why Human Review Exists

Human review enables safe delegation of work to operators while preserving accountability.

Compliance & Governance

• Financial approvals
• Legal and contract review
• Policy enforcement
• Audit and regulatory requirements

Quality Control

• Content moderation
• Output validation
• Data accuracy checks

Critical Decisions

• External customer communication
• Infrastructure or system changes
• Access and permission changes

Exception Handling

• High-value transactions
• Unusual patterns
• Edge cases and anomalies

How Human Review Works

Execution Pausing & Resumption

When an operator reaches a review step:

1. Execution pauses automatically
2. Reviewers are notified
3. A review form is generated with full execution context
4. A human submits a decision
5. The operator resumes execution based on that decision

Operators never bypass review steps unless explicitly configured to do so.

Review Forms

Review forms are generated dynamically and can include:

• Approve / reject actions
• Comments or rationale fields
• File uploads and attachments
• Multiple-choice decisions
• Conditional logic based on responses

Forms can be accessed inside Supervity or embedded externally.

Creating Human Review Steps

Using Operators (Recommended)

You can request human oversight in natural language:

“Send the drafted email to the manager for approval before sending.”

The operator will:

• Insert a review step
• Design the approval form
• Configure notifications
• Define resume behavior

This is the fastest and safest way to add human review.

Manual Configuration

You can also add review steps explicitly:

1. Add a Human Review step
2. Configure the form:
   • Fields (text, choice, file, etc.)
   • Required inputs
   • Reviewer instructions
3. Assign reviewers:
   • Specific users
   • Roles
   • External email addresses
4. Define timeouts and escalation rules

Review Experience

For Reviewers

Accessing Reviews

Reviewers receive review requests via:

• Email notifications
• In-app review dashboard
• Embedded external systems (Enterprise)

Each review includes:

• Context from earlier steps
• Relevant data and attachments
• Clear instructions on what’s required

Reviewer Actions

Reviewers can:

• Approve or reject
• Add comments
• Upload supporting files
• Modify inputs (if allowed)
• Escalate or delegate (if enabled)

All actions are logged and auditable.

For Workflow Owners

Monitoring Review Status

Each review moves through clear states:

• Pending
• Approved
• Rejected
• Timed out - nobody answered within the review window, so the run stopped waiting and ended. The form is closed at that point: opening it shows the submission read-only, and approving or rejecting it no longer does anything.

Status is visible in real time.

Audit Trail & History

Supervity records:

• Who reviewed
• When the decision was made
• The decision outcome
• Comments and attachments
• Impact on downstream execution

This supports audits, compliance, and retrospectives.

Configuration Options

Reviewer Assignment

Reviewers can be assigned as:

• Single reviewer
• Multiple reviewers:
  • Any one
  • All required
  • Majority-based
• Role-based (e.g. Manager, Admin)
• Dynamically based on workflow data

Notifications & Escalation

Notify reviewers via:

• Email
• Slack / Microsoft Teams
• In-app notifications

Escalation options include:

• Reminder after X hours
• Backup reviewers
• Hierarchical escalation

Timeouts

A review that nobody answers does not wait forever. Every review has a window, and when it runs out the workflow run stops waiting and ends with the status Timed out, naming the step nobody answered. The run is not marked failed: nothing broke, the decision simply never came.

A failed step waiting for someone to retry or skip it has a window too, but a shorter one. A review is easy to find — it appears in your review list and on your dashboard — whereas a failed step waiting on a retry shows up only on that run's own page. A long wait there would keep a run alive that nobody has been told about, so the retry window is sized for someone who is already watching.

How long the window is

Both windows come from your plan:

They are set per organization rather than per workflow, so every review in your workspace uses the same window. Administrators can adjust either for an organization, and on Business the review window can be set anywhere up to the platform maximum.

The upper bound is tied to how long the execution sandbox keeps a paused run's session alive. That is what guarantees a review answered inside the window resumes into a live session, and it is why a window cannot be extended without limit.

To carry on after a review times out, start the workflow again.

Common Human-in-Command Patterns

Approval Gate

Conditional Review

Multi-Level Review

Best Practices

Design Principles

• Use review only where judgment is required
• Provide full context to reviewers
• Keep forms concise
• Avoid unnecessary approval layers

Performance Considerations

• Set reasonable timeouts
• Use escalation paths
• Monitor review bottlenecks

Security

• Restrict reviewer access
• Protect sensitive data
• Enable audit logging

External & API-Driven Reviews (Enterprise)

Human review can be embedded into:

• External dashboards
• Command centers
• Internal tools

Using APIs, external systems can:

• Fetch pending reviews
• Render review forms
• Submit approve or reject actions
• Resume operator execution programmatically

See User Forms API.

Monitoring & Analytics

Track review performance using:

• Average review time
• Approval and rejection rates
• Bottlenecks
• SLA compliance

These insights help improve operational efficiency.

Troubleshooting

Review Not Received

• Check notification settings
• Verify reviewer permissions
• Resend review request

Workflow Stuck Waiting

• Check timeout configuration
• Escalate manually (Admin)
• Cancel or restart execution

Getting Started

• Tutorial: Approval Workflow
  /u/alpha/tutorials/library/advanced/human-approval-workflows

• Example: Expense Approval
  /u/alpha/tutorials/examples/content-approval-process

• View Pending Reviews
  Available from the Human Review dashboard

Human Review ensures operators act with autonomy, but never without accountability.