Flowgrammer

Box Document Approval Workflow

Run a named approve, reject, or request-changes path on files that already live in Box, bound to file id, file_version, and a decision log.

— Craig Major

You can run a named approve, reject, or request-changes path on files that already live in Box. Capture the file id and file_version, plus sha1 or etag when you have them. A decision evidence log, the decision log in this guide, binds each decision to that frozen version so a later upload cannot pretend to inherit yesterday’s yes. The Box Approval Folder / Decision Log Template gives you the folder names, that log, and seven worked cases.

Start from the published Document Approval Workflow if you still need the shared status and role model. Box stores and routes the file. It is not organizational authority.

Who this is for

Use this when controlled procedures already live in Box and the missing piece is a named decision on a frozen version.

The download includes:

  • Folder names for Intake, In Review, Changes-Requested, Approved, Rejected, and Exceptions
  • A setup checklist for collaborators, File Request, shared links, and Relay or Automate
  • A decision log with file id, file_version, optional sha1 and etag, reviewer, and outcome fields
  • Seven Cedar & Quay cases, including unauthorized actor, stale version, shared-link denial, timeout, and a duplicate webhook
  • An original notify-only reminder design. Reminders never change status

You still need one document family for the first build, named reviewers who can open the file as collaborators, and a place to keep the decision log. Confirm whether your plan includes File Request, Relay or Automate, shared-link password and expiry, and metadata before you promise those surfaces to a team.

Keep neighboring jobs on their own pages. If you still need to decide what to automate first, use Document Processing Automation. If the pain is unread PDFs, use intelligent document processing. Box Extract and Box AI Extract can extract invoice fields, but that is a separate, plan-dependent document-processing job and is not part of this approval template. If the job is a money register, use invoice processing automation or the Google Sheets invoice tracker. If the job is a renewal register, use the contract tracker. If the file lives in Dropbox, use the published Dropbox document approval workflow. If the file lives in Google Drive, use the published Google Drive document approval workflow. Box Sign is a separate signature workflow.

What Box adds to the shared model

The parent owns the control job: closed statuses, named authority, version lock, reminders that never auto-approve, and one idempotent downstream action. This page does not invent a second schema.

Box implements the file half and optional coordination surfaces:

  • Native file id plus nested file_version.id, with optional sha1 and etag
  • Review tasks with resolution approved or rejected, or general complete tasks
  • completion_rule of all_assignees by default, or any_assignee
  • Box Relay Approval Task or Box Automate as routing, not as the decision log
  • File Request as intake only
  • Shared links as access control, not identity proof
  • Webhooks V2 that still need an idempotent handler

The published Document Approval Status and Role Matrix stays the app-neutral field and status list. Parent closed statuses stay 1:1: draft, submitted, in_review, changes_requested, pending_escalation, approved, rejected, cancelled, superseded, duplicate. Box overlay statuses record access and exception states: access_verified, unauthorized_attempt_logged, external_access_denied, link_expired_or_denied.

Do not copy Drive Approvals lock or reset semantics onto Box. Drive has a native Approvals object. Box does not. Do not copy Dropbox folder rules onto Box tasks.

File identity, version, checksum, and etag

Prefer native file id over a path. Paths change when you move a file. Freeze identity when the row enters in_review:

  1. file_id
  2. file_version_id
  3. optional sha1
  4. optional etag
  5. path as a human pointer only

A later decision that cites a different file_version_id or sha1 is stale. Void it. Recapture metadata. Start a new cycle. Do not reuse the prior decision_id as current authority.

Official Box file docs, accessed 9 September 2026, expose id, etag, sha1, and a nested file_version mini object with its own id and sha1. You can retrieve a specific version by id. Version history exists when someone overwrites, uploads, or edits. This page does not invent a day-count retention window for those versions.

Tasks, Relay, and Automate

Box can assign a review task. Official task docs say action=review uses resolution states incomplete, approved, and rejected. action=complete uses incomplete and complete. completion_rule is all_assignees unless you set any_assignee. Tasks require collaborators on the file. A shared-link viewer is not a task assignee.

Box Relay can start from a file or folder event, a File Request, a task event, a schedule, or a Sign event. An Approval Task asks assignees to accept or reject. Every assignee must complete unless the workflow marks that only one assignee is required. Rejection can end the flow, return to a prior outcome, or assign a general task for a revision cycle. Workflow creators need Relay enabled and Editor or higher on the trigger folder.

Box Automate is the successor builder. Official 2026 docs say new features go to Automate, not Relay. A Point Migration path exists for Business and above. Migration is optional for now. Activating Automate deactivates Relay. Feature matrices gate branching, metadata, Forms, document generation, Sign request outcomes, and AI agents by plan. Confirm the matrix in your tenant before you promise those outcomes.

A task click, a Relay run, or an Automate path can be the channel that collected the decision. It becomes evidence only when the decision log also stores the named actor, timestamp, file id, file_version, and outcome. Folder moves and metadata enums are coordination. They are not the record.

Decision log fields

The decision evidence log (DecisionEvidence) is the durable record. After this section, this page calls it the decision log.

Every terminal action writes a row. The reader columns are:

Field Job
request_id Stable request key
file_id Box native id
file_version_id Frozen version
sha1 Optional checksum
etag Optional freshness signal
requester Named person
approver Named matrix actor who decided
decision approve, reject, or request_changes
decided_at When the person decided
rationale Why, required on reject or changes
next_action notify, move_to_approved, hold, or none

Keep the parent keys beside those columns: decision_id, authority_rule_id, duplicate_key as lower(file_id)|lower(file_version_id), idempotency_key as request_id|decision_id|action, downstream_write_count as 0 or 1, and access_test_result.

Comments, shared links, file requests, folder names, task rows, version-history previews, and Box Sign receipts may be linked as discussion or access refs. They never stand alone as approval evidence.

Comments, links, file requests, folders, and Sign

A comment that says “looks good” is not approved. A shared link is access, not authority. Password and auto-expiration are not available on free Individual accounts. Custom URL endings are Business and Enterprise. Admin settings can restrict who may create links.

File Request can collect a file, including from people without Box accounts unless an admin requires login. Creating a File Request needs a Business plan or higher. Collection is intake. It is not approve or reject.

A folder named Approved is not approval. Version history can show what changed. It is not a closed decision.

Box Sign is a separate signature request. Relay and Automate can listen for Sign events, and a Sign recipient role can be labeled Approver. That role is still e-sign. It is not this internal decision log.

Worked example

Cedar & Quay Fabrication Ltd is a fictional Toronto fabricator. Quality owns supplier procedure DOC-CQ-PROC-014. Version 1.4 is the candidate. Jordan Hale is the Quality Coordinator. The file sits in folder CQ-Quality-Controlled. Morgan Reid (Ops Manager) is the named approver. Avery Chen (Quality Lead) is escalation. Riley Patel is an unauthorized teammate.

Jordan confirms Morgan can open the file as a collaborator, captures file_id id:FICTION-BOX-CQ-PROC-014 and file_version_id ver:box-cq-014-v14, then assigns a review task. The decision log stores request REQ-CQ-2026-0921, both keys, optional sha1, Morgan, approve, decided_at, rationale, and next_action move_to_approved. Write count stays 1.

That clean path is case 1 in the Box Approval Folder / Decision Log Template. The other six cases reuse the same document family.

The Box approval workflow

  1. Intake. A file lands in the controlled library by upload, shared-folder drop, or File Request. Register request_id, requester, and a pointer. Do not approve on upload.
  2. Access. Confirm each named reviewer is a collaborator who can receive a task, not only a shared-link visitor. Failures become external_access_denied or link_expired_or_denied.
  3. Identity. Capture file id and file_version. Refuse in_review if identity is missing.
  4. Coordinate. Assign a review task, or start a Relay or Automate Approval Task if your plan includes it. Record the task or workflow id as a channel ref.
  5. Decide. The named reviewer approves, rejects, or requests changes. Write the decision log for that named act.
  6. Remind and escalate. Notify when due_at approaches. After timeout, set pending_escalation and reassign to the escalation approver. Timeout does not approve.
  7. Invalidate stale versions. If someone uploads a new version, a log row that still cites the old file_version_id or sha1 is stale_version.
  8. Stop duplicates. A second request for the same file_id|file_version_id is duplicate. A replayed webhook with the same decision_id is ignored. Write count stays 1.
  9. Handoff. After approve, move or shortcut once to the Approved folder. Retry with the same idempotency key.
  10. Evidence. Export the log. Keep comments, tasks, Relay runs, and Sign receipts as support, not as the decision.

If you later add an integration, official webhook docs prefer V2. Respond 200 to 299 within about 30 seconds. Box may retry up to 5 times. Verify signatures and treat BOX-DELIVERY-TIMESTAMP as a freshness check. Exact numeric rate quotas are unpublished. A webhook is not a decision-log row.

What can run automatically, and what cannot

Situation Automatic action Person required
File uploaded or File Request received Optional notify No
Reviewer is only a shared-link visitor Stay out of in_review Owner invites a collaborator
Named reviewer approves on the frozen version One Approved-folder write after the log row The decision itself
Reviewer rejects or requests changes Hold; wait for a new file_version Owner uploads the revision
Actor not on the matrix Exception unauthorized_approver Process owner. Status stays in_review
Decision cites an old file_version Exception stale_version Restart on the current version
Webhook replay Ignore the second write Confirm write count 1
Shared link expired or password failed Status link_expired_or_denied Replace reviewer or fix the link
SLA missed Notify, then escalate Escalation approver. No auto-approve
Payment or bank-detail change Never Entirely outside

Human decisions

A person keeps these decisions:

  • Approve, reject, or request-changes
  • Authority and self-approval conflicts
  • Whether a task, Relay, or Automate path may be the channel
  • Stale-version restarts after an upload
  • Duplicate versus canonical request
  • External-access or shared-link failures
  • Escalation after timeout
  • Whether Box Sign is even in scope, as a separate job
  • Payment release and any supplier bank-detail change

A comment can send a person to the file. It cannot approve. A shared link cannot approve. A File Request cannot approve. A folder move cannot approve. A task row without a decision-log row cannot approve. Timeout cannot approve.

Failure paths

Failure Expected status Downstream Payment
Unauthorized actor or comment-as-approve in_review plus unauthorized_approver No write Blocked
Stale file_version or sha1 stale_version, still in_review No write Blocked
Duplicate start or replayed webhook duplicate No second write Blocked
External-access denial external_access_denied No decision yet Blocked
Shared link expired or denied link_expired_or_denied No decision yet Blocked
Timeout with no person pending_escalation No auto-approve Blocked
Missing file id or file_version submitted No start Blocked
Task or Relay without a log row Exception task_or_relay_without_contract No internal approve Blocked
Box Sign treated as approve Exception sign_confused_as_approval No internal approve Blocked
Any payment or bank-detail change Forbidden Forbidden Forbidden

Test cases

The seven Cedar & Quay cases are control fixtures. They are not customer results.

Case Input Without the decision log After the control
Clean approve DOC-CQ-PROC-014 v1.4, Morgan named File sits in In Review approved plus one Approved-folder write
Request changes then new version Morgan asks for section 4 Old comment looks like progress New file_version; prior decision not reused
Unauthorized approver Riley comments "approved" Status flipped by chat unauthorized_approver; reviewers unchanged
Stale version Approve cites v1.4 after a new upload Wrong version marked approved Void; recapture current file_version
External or shared-link denial Supplier has only an expired link Link treated as approve external_access_denied or link_expired_or_denied
Timeout / escalation due_at 1 September 2026, as_of 9 September Silence treated as approve pending_escalation to Avery Chen
Duplicate / idempotent callback Webhook replay for the same decision_id Second Approved write First write wins; write count 0 on the replay

The paired template walks each case on its own sheet and in csv/case-recalc.csv.

What to measure

Record requests received, share of rows with file id and file_version captured, unauthorized attempts blocked, duplicate notifications suppressed, timeouts escalated without auto-approve, access tests passed before in_review, and approvals that have a folder or log write ref. Keep those as definitions. Do not invent a benchmark, accuracy rate, or ROI figure.

There is no live production Box approval metric here, and no Flowgrammer customer Box case.

How to use the template

Download the Box Approval Folder / Decision Log Template. It is an editable workbook and CSV pack, not a Marketplace listing and not a live Box file.

  1. Read README.md, then markdown/setup.md.
  2. Walk FolderNamingConvention and PlanGatesChecklist. Confirm File Request, Relay or Automate, and shared-link settings in your tenant before production.
  3. Import csv/decision-evidence-import.csv. Keep the internal names.
  4. Leave Config as_of at 9 September 2026 while you walk Case01 through Case07.
  5. Confirm case 3 does not move to Approved and case 7 does not write a second time.
  6. Answer the security, retention, and Sign-separation questions. Labels and metadata alone are not a records program.

The useful rules also sit on this page so the download is not the only answer. Packaged formulas use the Config as_of date and do not call TODAY().

Realistic limitations

  • Box stores and routes the file. It does not become organizational authority.
  • Review tasks, Relay, and Automate are plan- and admin-gated. Confirm the current official matrices in your tenant.
  • File Request needs a Business plan or higher to create.
  • Shared-link password and expiry are not available on every account.
  • Sequential multi-step routing is a Relay or Automate overlay, not a second status model.
  • Webhook retries exist. Exact API rate quotas are unpublished.
  • Tenant screens differ. Confirm the screens you actually see.
  • This system does not sign a document, pay anyone, run OCR, or change supplier bank details.
  • This guide does not rank Box against Dropbox, Drive, or SharePoint, and it is not an e-sign buyer’s guide.
  • This page is operational guidance, not legal advice and not a compliance certification.

Next step

Download the Box Approval Folder / Decision Log Template for the folder names, decision log, and seven worked cases.

Keep the parent Document Approval Workflow and Document Approval Status and Role Matrix nearby for the shared model.

If reviewers, authority, or the destination log are still unclear, start with an AI Success Audit. If those pieces are already named, book a fit call to scope an AI Automation Systems build.

Sources

Frequently asked questions

What is a Box document approval workflow?

It is a named approve, reject, or request-changes path for a file that already lives in Box, bound to file id and `file_version`, and written to a decision log. Tasks, Relay, and Automate can coordinate the work. Comments, shared links, file requests, folder names, task completion, version history, and Box Sign are not the decision.

Do Box review tasks replace the decision log?

No. A review task can collect accept or reject from collaborators. The decision log still stores the named actor, timestamp, file id, `file_version`, and outcome.

Is Box Relay the same as Box Automate?

Relay is the linear builder. Automate is the successor with plan-gated branching and later features. Official docs say new features go to Automate. A migration path exists and is optional for now. Confirm which builder your tenant actually has.

Are comments or shared links enough?

No. Comments are collaboration. Shared links are access. Keep a named decision row.

Does a new upload cancel an approval?

A decision that still cites the old `file_version_id` or sha1 is stale. Void it and start a new cycle on the current version.

Is this the same as Box Sign?

No. Box Sign is a signature request. A Sign recipient labeled Approver is still e-sign. A file may need both under a separate policy.

Can timeout auto-approve?

No. Timeout becomes pending_escalation. A person still decides.