Learning PathModule

Approval Flows in action

Follow a live Approval Flow as it moves through tiers, see how approvers are determined, and learn why a single rejection stops everything.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Explain how and when an Approval Flow is created and what state it carries.

  • Read the flow fields that determine who can act now.

  • Describe approval, rejection, and the concurrency control that protects the flow.

The Approval Rule is the policy. The Approval Flow is the live case file for one Order: it records who has approved, who still must, and whether anyone has rejected. Where the previous pages designed governance, this page runs it.

How a flow begins

When a buyer places an Order that matches an active Approval Rule, the platform creates an Approval Flow automatically. The Approval Flow is the runtime record for that Order: it references the matched rules, records approvals or rejection, and exposes the role-based approver fields a buyer portal needs to decide who can act next.
GET /{projectKey}/as-associate/{associateId}/in-business-unit/key=atlas-apac/approval-flows/{approvalFlowId} HTTP/1.1

{
  "id": "a1b2c3d4-0000-0000-0000-000000000001",
  "version": 1,
  "status": "Pending",
  "order": { "typeId": "order", "id": "8f2e..." },
  "approvals": [],
  "eligibleApprovers": [
    { "associateRole": { "typeId": "associate-role", "key": "apac-manager" } },
    { "associateRole": { "typeId": "associate-role", "key": "finance-director" } }
  ],
  "pendingApprovers": [
    { "associateRole": { "typeId": "associate-role", "key": "apac-manager" } },
    { "associateRole": { "typeId": "associate-role", "key": "finance-director" } }
  ],
  "currentTierPendingApprovers": [
    { "associateRole": { "typeId": "associate-role", "key": "apac-manager" } }
  ]
}

Who can act now: eligibility is role-based

Use the approver fields on ApprovalFlow for two different portal decisions. currentTierPendingApprovers drives who should be notified now. eligibleApprovers helps gate approve and reject actions for Associates whose roles are still eligible in the hierarchy.
Treat them as role checks, not person checks. Match the Associate's roles against eligibleApprovers for action eligibility. Match them against currentTierPendingApprovers to decide whether their approval is needed in the currently active tier. The broader pendingApprovers field shows roles still required across all remaining tiers.

The frontend reflects these fields; the platform enforces whether the Associate can act.

Because an Associate is matched on all their roles, someone who holds two roles spanning different open tiers can act more than once. The platform, not the frontend, enforces this; the frontend only reflects it.

Notifying approvers

The platform does not send approval notifications on its own. It exposes who to notify through currentTierPendingApprovers, but delivering the message is the integration's job. Wire it with the platform's eventing:
  • Create a Subscription for the Approval Flow Messages, such as ApprovalFlowCreated and ApprovalFlowApproved, delivered to a message queue.
  • In the handler, read currentTierPendingApprovers on the flow, resolve the Associates who hold those roles in the Business Unit, and notify them by email or a portal alert through your own channel.
This keeps notification logic in your integration while the platform stays the source of truth for who is eligible to act. A buyer portal also commonly surfaces pending work directly by querying Approval Flows in the Pending status.

Approving and rejecting

Both actions are update actions on the Approval Flow, requiring the manage_approval_flows scope.
An Associate approves with the approve action. When every role required across all tiers has approved, the platform automatically sets status to Approved.
POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=atlas-apac/approval-flows/{approvalFlowId} HTTP/1.1
Content-Type: application/json

{
  "version": 1,
  "actions": [ { "action": "approve" } ]
}
An Associate rejects with the reject action, optionally giving a reason.
POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=atlas-apac/approval-flows/{approvalFlowId} HTTP/1.1
Content-Type: application/json

{
  "version": 1,
  "actions": [ { "action": "reject", "reason": "Over budget for this quarter" } ]
}
A single rejection rejects the entire Approval Flow, and the Order receives the rejection. Rejection is not scoped to one tier or one approver: as soon as any eligible approver rejects, the flow's status becomes Rejected and no further approval can revive it. An Associate may also change a prior approval into a rejection while their tier is still open.

Concurrency: read the version, then write

Approve and reject are read-then-write operations. Notice the version field in each request body: you fetch the flow's current version, then submit it with your action. If another approver has acted in the meantime, your version is stale and the platform rejects the update with a 409 Concurrent modification error.

Optimistic concurrency stops two approvers from acting on the same flow at the same time and corrupting its state. Always base an approval or rejection on a freshly read flow, and treat a 409 as "someone else acted, re-read and reassess." Do not retry without checking the latest state.

The flow state machine

Worked example: tracing an Atlas flow

Atlas APAC has a two-tier rule: tier one requires apac-manager, tier two requires finance-director. A buyer places a qualifying AUD 60,000 order. Trace both outcomes.
  1. Flow created. The platform creates the flow as Pending. currentTierPendingApprovers lists apac-manager; finance-director is in pendingApprovers but not yet current, because tier two is not open.
  2. Tier one approves. A manager reads the flow (version: 1) and submits approve with that version. The flow advances; currentTierPendingApprovers now lists finance-director.
  3. Approval path. The finance director reads the now-current flow (version: 2) and approves. All tiers are satisfied, so the platform sets status to Approved and the Order proceeds.
  4. Rejection path. If instead the finance director submits reject with a reason, the whole flow becomes Rejected immediately and the Order receives the rejection, regardless of the manager's earlier approval.
  5. Concurrency. If two managers both read version: 1 and both submit approve, the first succeeds and bumps the version; the second receives 409 Concurrent modification and must re-read the flow before deciding whether any action is still needed.

Key takeaways

  • The platform creates an Approval Flow automatically when an Order matches an active rule; it starts Pending and references the Order.
  • Eligibility is role-based: gate actions on currentTierPendingApprovers (needed now) and eligibleApprovers (any open tier).
  • All tiers must approve for Approved; a single rejection sets the whole flow Rejected, and the Order receives the rejection.
  • Approve and reject are read-then-write: submit the current version, and treat 409 Concurrent modification as "re-read and reassess."
  • The platform sends no approval notifications; subscribe to Approval Flow Messages and use currentTierPendingApprovers to notify the right approvers yourself.

Test your knowledge