Learning PathModule

Approver hierarchies and tiers

Encode real sign-off chains as an approver hierarchy of tiers, using AND and OR logic to model "two of these, then the director".

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Describe the structure of an approver hierarchy and its tier, conjunction, and disjunction levels.

  • Use AND and OR logic to model parallel and alternative approvers within a tier.

  • Sequence multiple tiers to model escalating sign-off.

"Either regional director signs off, then the finance director, then we're done." Real approval chains mix alternatives ("either of these people") with requirements ("and then this person"), and they run in a defined order. The approvers field of an Approval Rule captures exactly this shape with a hierarchy of tiers.

The shape of an approver hierarchy

The ApproverHierarchy has three nested levels. Reading from the outside in:
  • tiers: an ordered array of one to five tiers. Every tier must be approved, in order, for the hierarchy to complete.
  • Within a tier, and: a list of groups that must all be satisfied (logical AND).
  • Within a group, or: a list of approver roles where any one satisfies the group (logical OR).
Each leaf is a RuleApprover pointing at an Associate Role. So the structure reads: all tiers, in order → all AND-groups in a tier → any one OR-approver in a group.
The Associates overview in the API reference diagrams this structure alongside the end-to-end approval process; see Intended workflow for the full set of tier, conjunction, and disjunction visuals.
A hierarchy may have at most five tiers. If your governance needs more sequential stages than that, you are likely modeling an organizational process that belongs partly in an external system; revisit the requirement before trying to force it into the hierarchy.

Building up the logic

Start simple and add only the structure you need.

One approver. A single role in one tier is the minimal hierarchy. Any holder of apac-manager approves.
POST /{projectKey}/as-associate/{associateId}/in-business-unit/key=atlas-apac/approval-rules HTTP/1.1
Content-Type: application/json

{
  "name": "Manager sign-off",
  "status": "Active",
  "predicate": "totalPrice > \"2000.00 AUD\"",
  "requesters": [ { "associateRole": { "typeId": "associate-role", "key": "apac-buyer" } } ],
  "approvers": {
    "tiers": [
      { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "apac-manager" } } ] } ] }
    ]
  }
}
AND/OR within one tier. "Either regional director, and the compliance reviewer." Two AND-groups in one tier; the first group offers a choice of two directors.
{
  "tiers": [
    {
      "and": [
        {
          "or": [
            { "associateRole": { "typeId": "associate-role", "key": "apac-director" } },
            { "associateRole": { "typeId": "associate-role", "key": "apac-deputy-director" } }
          ]
        },
        {
          "or": [
            { "associateRole": { "typeId": "associate-role", "key": "compliance-reviewer" } }
          ]
        }
      ]
    }
  ]
}
Here a director (either one) and a compliance reviewer must both approve, but they are in the same tier, so they can approve in any order relative to each other.
Sequential tiers. "Managers first, then the finance director." Two tiers, evaluated in order: the second tier does not open until the first is fully approved.
{
  "tiers": [
    { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "apac-manager" } } ] } ] },
    { "and": [ { "or": [ { "associateRole": { "typeId": "associate-role", "key": "finance-director" } } ] } ] }
  ]
}

Design for approver absence

An approver hierarchy that names a single approver stalls the moment that person is on vacation, is reassigned, or is deactivated. Because approvers are Associate Roles rather than individuals, several people can hold the approving role, but a rule still blocks if no active holder is available. Design for absence from the start:

  • Assign approving roles to several people. More than one holder of a role means any of them can clear the tier.
  • Use OR groups for interchangeable approvers. An or of two roles, such as a director and a deputy director, lets either approve when the other is away.
  • Provide a higher-tier fallback. A senior role, or a manager who also holds a routine approver's role, can step in when the usual approver is unavailable.

Governance that cannot be satisfied is worse than none, because it silently blocks legitimate orders. Build at least one backup path into every tier that would otherwise depend on one person.

Tracking who is needed now

As a hierarchy progresses, the platform exposes which roles are still required in the currently active tier through the Approval Flow's currentTierPendingApprovers field. That field is what a buyer portal reads to notify the right people at each stage, and you will use it on the next page when tracing a live flow. Designing the tiers well here is what makes those notifications meaningful: each tier should correspond to a real decision point in the organization.

Worked example: three Atlas approval shapes

Design approver hierarchies for three escalating Atlas APAC scenarios, all on top of the threshold predicates from the previous page.

  1. Routine spend (single approver). Orders over AUD 2,000: one tier requiring apac-manager. Fast, single sign-off for everyday purchasing.
  2. Significant spend (AND/OR in one tier). Orders over AUD 5,000: one tier where either apac-director or apac-deputy-director approves, and finance-controller approves. The OR gives cover when one director is unavailable; the AND guarantees finance always sees it.
  3. Strategic spend (sequential tiers). Orders over AUD 50,000: tier one is the significant-spend tier above; tier two adds finance-director alone. The large deal must clear the same controls and then escalate to a final sign-off, in order.

Each design uses only as much structure as the decision needs, and never more than five tiers.

Key takeaways

  • An approver hierarchy is tiers (1–5, ordered) → and groups (all required) → or approvers (any one required); each leaf is an Associate Role.
  • All tiers must approve in sequence; within a tier, AND-groups can be satisfied in any order.
  • Use OR for interchangeable approvers (cover for absence) and AND for mandatory parallel approvers (such as finance plus a director).
  • Design for approver absence: assign approving roles to several people, use OR groups for interchangeable approvers, and provide a higher-tier fallback so one person's absence cannot block an order.
  • The active tier's outstanding roles surface as currentTierPendingApprovers, which drives stage-by-stage notifications.

Test your knowledge