Submitting for approval
What this page is — what happens, check by check, when an author submits a document, and how its route to an approver is decided.
What it is for — so a document reaches the right approvers by a route defined in advance.
The problem it solves — "who needs to approve this?" answered per document is answered differently every time, and nobody can show afterwards that the right person did.
Route: /org/papers/documents/<document> → the lifecycle's submit button · Permission:
Edit draft documents / data values. to submit; Act on approval steps (approve/reject/return). to decide
1. What it is
Submitting is a lifecycle transition, usually with action submit. It is also the moment Papers decides
whether a decision is needed and who makes it.
| Submitting | Finalizing | A lifecycle "send" step | |
|---|---|---|---|
| Asks for a decision | Yes, if the target state is approval-gated | No | No |
| Checks required fields | Yes — only this action | No | No |
| Locks editing | Yes, once the state is no longer editable | Seals permanently | Depends on the state |
| Contacts anyone | Approvers, through the workflow | No | No |
The button carries the transition's label, so it may read Submit, Submit for review, or whatever your organisation named it.
2. Why you would use it
- The right people approve, every time. The route is defined once, on the type, and can depend on values like contract size. It is not decided per document by whoever the author remembers.
- A big deal can't take a short route. A guardrail forces high-value documents through the full chain whatever the transition says, and records that it did.
- Reviewers see a stable document. Once submitted, the content stops changing under them.
- Nobody approves their own work. The person who submitted cannot approve it, unless your organisation explicitly allows that.
3. What happens when you submit
How the route is chosen
- The transition's default workflow, set on the type's lifecycle.
- The value matrix, if configured. It picks a workflow from field values, e.g. above ₹10 lakh use Finance + Legal.
- The approval guardrail, applied last. If a field is over the threshold, or the value is missing, the guardrail's workflow is forced. An approval guardrail enforced event records the field, threshold, observed value and workflow name.
4. Field reference — refusals and their exact messages
| Message | Cause |
|---|---|
| "missing required fields: Governing law, Contract value" | Visible required fields are empty. Only checked when the action is literally submit |
| "action "submit" is not allowed from state "…"" | The lifecycle has no submit from this state |
| "this document is waiting on an approval decision (…)…" | It is already in approval — act from the inbox |
| "state requires approval but the approval engine is not configured" | Platform configuration — tell your administrator |
| A sentence about an inactive or misconfigured workflow | The workflow's own message, e.g. a workflow that is inactive — fix it in the Type Designer |
| "this blueprint routes on a value, so it needs a field and a threshold before it can be planned" | A value-based approval blueprint is incomplete |
submitIf your type's submit transition uses another action code, such as send_for_review, required fields
are not checked. Name the transition's action
submit, or check completeness yourself.
5. When nothing was routed
If the target state is an approval state but no workflow resolves, the document still moves and waits there. It appears in the inbox's Waiting for a decision — not routed section, and two rules protect it:
| Rule | Message when broken |
|---|---|
| Deciding needs Act on approval steps (approve/reject/return). | ""approve" is an approval decision and needs the Papers approval permission…" |
| The submitter cannot approve it | "you submitted this document, so you cannot approve it yourself — someone else with approval rights has to…" |
Moves that send the document back — reject, return, withdraw, anything landing in an editable state —
need neither. An author can always pull their own submission back. A one-person organisation can allow
self-approval with the system setting papers.allow_self_approval.
Editable states are draft, negotiation and returned. Once a document leaves them, its fields are read-only. Reopening needs an administrator override, which requires a target state and a reason: "reason is required for an admin override".
6. Worked example
Arjun submits Vendor Agreement VA-2026-077 (value ₹38,00,000) with the comment "Standard terms, new vendor."
- The type's submit transition defaults to the Manager approval workflow.
- The value matrix says values over ₹25 lakh use Manager → Finance, so that workflow is chosen.
- The guardrail says values over ₹30 lakh must use Manager → Finance → Legal. It forces that workflow, and Activity records the field, threshold, value and forced workflow name.
- The engine routes the document. Step 1 names the persona reporting manager, but Arjun has none recorded, so the step goes to the organisation owner. Their card says: "Routed to you as the organization owner: the step's persona (reporting manager) resolved to nobody on this document."
- Arjun tries to edit the payment terms and cannot — the document is in pending approval.
- Finance returns it with "Add the bank guarantee clause." It lands in returned, which is editable. Arjun adds the clause and submits again.
7. The admin contract
| What must be configured | Otherwise |
|---|---|
| A workflow on each approval transition (lifecycle) | Documents land unrouted, and nobody is notified |
States marked kind: approval only where a decision is really needed | Decisions are demanded where nobody expects them |
Submit transitions with action code submit | Required fields are not enforced |
| Personas that resolve for every document, e.g. reporting managers recorded | Steps fall back to the organisation owner |
| A guardrail on high-value types | Value-based routing can be bypassed by the transition default |
papers.allow_self_approval only for single-person organisations | — |
8. Downstream
- Approvers see the document in the approvals inbox.
- A pending approval blocks every other lifecycle move from the document page.
- Readiness checks on the type warn when a step's persona may resolve to nobody.
- Approval routing advice can review whether the chosen route fits the document.
9. Don't confuse this with…
| Finalize and numbering | Seals the document. Submitting asks for a decision |
| Sending to a counterparty | External negotiation. Submitting is internal |
| Admin override | Forces a state with a reason, bypassing the route — audited |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| Submitted with empty required fields | The transition's action is not submit |
| Nobody was notified | No workflow resolved — the document is in the unrouted section |
| It went to the organisation owner | A persona resolved to nobody (§6, step 4) |
| A cheap document took the long route | The guardrail treats a missing value as over the threshold |
| You cannot approve your own unrouted document | The self-approval rule (§5) |
| A 400 error mentioning a workflow | The workflow is inactive or misconfigured — its message says where |