Approvals

Realm9's approval system provides governance and control over environment access through configurable multi-level approval workflows. Workflows can be applied to booking requests, environment requests, and decommission requests.

---

Approvals Page

Navigate to Approvals in the sidebar to see a centralised view of all workflow instances — both active (in progress) and completed. From here you can:

• View pending approvals assigned to you
• Review approval history for requests you submitted
• See the current level and progress of any workflow instance
• Take approval actions directly

---

How Approvals Work

Approvals govern the main workflow trigger across Bookings, Environment Requests, and Decommission Requests. When a user submits one of these, Realm9 checks whether an approval workflow applies:

• With a workflow: A workflow instance is created and approval steps are sent to the configured approvers. The request progresses through each level in order. When all levels are approved, the request is activated automatically.
• Without a workflow (Direct Admin Approval): The request stays in Pending status and requires an Admin or Super Admin to approve or reject it directly. This path does not support Additional Forms — there's no workflow instance for a request to go on hold against.

---

Workflow Types

Workflows are created under Configuration → Workflows and apply to one of three resource types:

• Booking Request — triggered when a user creates a booking on an environment that requires approval
• Environment Request — triggered when a user submits an environment provisioning request
• Decommission Request — triggered when a user submits a request to decommission an environment

---

Configuring Workflows

Path: /configuration/workflows

Admins can create, edit, activate, and deactivate workflows from this page.

Workflow Properties

• Name — display name for the workflow
• Description — optional notes for admins
• Resource Type — Booking Request, Environment Request, or Decommission Request
• Timeout — optional overall timeout in hours; if no decision is made within this period, the workflow is auto-rejected
• Send Reminders — if enabled, pending approvers receive reminder notifications
• Reminder Interval — how frequently reminders are sent (in hours)
• Is Active — inactive workflows are not applied to new requests; workflows with active instances cannot be deactivated until those instances complete

Assigning Workflows to Environment Types

For Environment Request and Decommission Request workflows, you can target:

• All environment types — the workflow applies to every request of that type regardless of environment type
• Specific environment types — the workflow only applies to requests for the selected types

If multiple workflows could apply, the type-specific workflow takes precedence over an all-types workflow.

---

Approval Levels

Each workflow has one or more approval levels that execute in sequence. Once the required number of approvals at a level is reached, the workflow advances — remaining pending steps at that level are left open but the next level begins.

Level Properties

Approver Types

Specific Users — named individuals are assigned approval steps. You specify the exact users when configuring the level.

Role-based — all active users with the specified role(s) receive approval steps (e.g. all ADMIN users, all PROVISIONER users).

Parallel vs Sequential Execution

• Parallel: All approvers at the level receive their step at the same time. The level passes once the required number approve.
• Sequential: Approvers receive steps one at a time. The next approver's step is created only after the previous one approves.

---

Post-Approval Stages

Environment Request and Decommission Request workflows can also define what happens after the last approval, on the workflow form's Post-Approval tab. Booking workflows don't have these stages.

There are two optional stages, each assigned either to specific users or to roles:

• Provisioning (on decommission workflows: Decommissioning) — who carries out the work once the request is approved. With this stage configured, approval alone doesn't finish anything: an approver hands the request over (Send for Provisioning / Send for Decommissioning), and the assigned person does the work and marks it done.
• Closure — who finishes the request at the end: Create Environment on environment requests, Confirm & Close on decommissions. Left off, the finishing action stays with Provisioners, Admins, and Super Admins.

Both stages are optional and independent — configure either, both, or neither. An unconfigured stage is simply skipped, and the request behaves exactly as it did before stages existed.

How stage assignment differs from approval levels:

• Role assignments are evaluated live. Whoever holds the role when the stage is ready can act — unlike role-based approval levels, whose steps are issued to the people holding the role at the moment the level starts.
• Changing a workflow's stage assignees applies immediately, including to requests already sitting in that stage — which is also the recovery path if an assignee leaves mid-request.
• A named-user stage emails the people it names. A role-based stage emails whoever its Who to notify setting names — see Who a role-based step tells. Either way it is one message, when the work starts waiting; once somebody takes it on, they get the assignment email with the deadline and the rest of the pool hears no more about it. Everyone with a matching role sees the request under Needs my attention throughout.

The configured stages appear on the workflow's card under Configuration → Workflows, in the workflow preview on request forms, and as stops on each request's progress card — with the assigned people, who acted, and when.

Assign and Reassign

Taking ownership of the work is one button, and it changes its wording to match the state of the request:

• Assign — shown while nobody owns the work yet. Handing it over sends the request into Provisioning (or Decommissioning) and starts that stage's SLA clock.
• Reassign — shown once somebody already owns it. This is a deliberate hand-over: it changes who is responsible and nothing else.

Reassignment inherits the clock exactly as it stands, breach included. A late request stays late under its new owner, so passing work around cannot be used to reset a missed target.

Reassignment is only possible while the work is still open. Once it has been marked done — Provisioned on an environment request, Decommissioned on a decommission — the assignment is a record of who did the work, and it can no longer be changed. The button is not offered at that point, and a request sent directly to the API is refused with a conflict rather than quietly rewriting finished history.

Whoever is eligible may add or remove anyone the stage could have named; the two words describe the request's state, not different permissions. Because the change replaces the whole owner list, the picker opens with the current owners already ticked — untick to remove, tick to add.

See Environment Requests and Decommissions for how the stages play out on each request type.

---

Making Approval Decisions

Eligible approvers can act on pending steps from:

• The Approvals page
• The booking detail page (Workflow tab)
• The environment request detail page
• The decommission request detail page

Available Decisions

An approver can also attach an additional form instead of deciding right away — see Additional Forms. This pauses the whole workflow (On Hold) rather than recording a step decision.

An optional Decision Notes field lets approvers add a comment or reason with Approve/Reject.

Decision notes are recorded per step — each approver writes their own. They are shown on the request's Workflow tab: a level that has notes shows a Note (or Notes (2)) link, collapsed by default, which expands to show what each approver wrote against their name. Notes are not included in notification emails.

When a Level Completes

Once the required number of approvals for a level is reached:

• The next level is created and its approvers are notified
• If it was the final level, the workflow is marked Approved and the underlying request is activated

When a Rejection Occurs

• The workflow is immediately marked Rejected
• Any remaining pending steps are cancelled
• The requester receives a notification with the rejection reason

---

Workflow Instance Statuses

---

Admin Override

Admins and Super Admins can override a pending or on-hold workflow level from the workflow instance detail view:

• Approve the current level, bypassing normal approver requirements
• Reject the workflow entirely
• An optional reason can be provided

Override doesn't apply to a Timeouted workflow — use Extend Timeout for those instead (below). All overrides are logged in the audit trail.

---

Extending a Timed-Out Workflow

If a workflow reaches Timeout, an Admin or Super Admin can reopen it instead of leaving the request stuck:

1. Open the workflow instance and use Extend Timeout
2. Optionally provide a reason
3. The workflow and its linked request are restored to an active approval state, and the original timeout duration is reapplied starting from now — approvers are notified

If the request still had an unsubmitted additional form when it timed out, extending returns it to Awaiting Info and the workflow to On Hold, rather than straight back to Pending.

---

SLA Targets and Warnings

Each approval level, and each post-approval stage, can carry a target for how long it should take.

• SLA target — how long this level or stage should take. Leave it blank to measure the time without promising anything: the clock still runs and the elapsed time is still reported, it simply has nothing to be compared against.

• Warn before — how long before the target the request should start counting as At risk. With a 4 hour target and a 1 hour warning, the request is On track for its first three hours and At risk for the last one. Leave it blank for no warning, and the request goes straight from On track to Breached. Setting a target for the first time suggests a quarter of it, which you can change or clear.

  This is a status threshold, not a mail setting. It decides when the At risk chip appears on the request and when the list's At risk filter starts matching it — see At risk below. The warning email is a separate thing that happens to be triggered from the same threshold; changing one changes when both happen, but a request is At risk whether or not anybody was successfully emailed.

A target is measured in business time: weekends do not count, and if a working-day window is configured, neither do the hours outside it. Time spent on hold does not count either — including time waiting on an additional form. Hold requires a reason, which appears on the workflow card's current step. Attaching an additional form writes its own reason on that same card, naming who asked and which sections they picked — you don't type that one.

A target belongs to the workflow, but a running request keeps the one it started with. Editing or clearing a target changes future requests only. A request already in flight measures against the target, working hours and warning time that applied on the day it started, so a configuration change today cannot make last quarter's numbers move.

At risk

At risk means the warning time has been reached and the target has not yet been missed. It is not only a list filter — it is shown as a status chip on the request itself, beside the countdown, so the state is visible on the record and in the list at once.

The order is: On track until the warning time is reached, At risk from there until the target passes, Breached after it. A request with no warning configured never shows At risk. A paused clock reports Paused instead, since what matters then is that the work is stopped.

Warning emails

Reaching the warning time also sends one email to whoever owns the work. This is delivered by a background check that runs every few minutes, so a warning set closer than that may arrive late — or not at all, if the target passes in between. The form says so when you choose one that short; it does not stop you.

A late or undelivered email does not change the status: the chip is computed from the clock whenever the request is read, so a request is At risk on the record and in the list at the right moment regardless of what the mailer managed to do.

---

Workspace Attachment Requirement

For booking request workflows, individual approval levels can be configured to require that Terraform workspaces are attached to the booking before the level can be approved. If workspaces are missing, the approval action is blocked with a prompt showing how many workspaces are still required. See Booking Provisioning for how workspace attachment works.

---

Notifications

Who a role-based step tells

A level or stage can name specific people or a role. When it names people, those people are its recipients and there is nothing to choose.

When it names a role, Who to notify decides who hears about it:

Two things this setting does not do:

• It never decides who may act. Anyone holding the role can still approve, claim or close exactly as before, whether or not they are told.
• It never hides the work. Everyone with a matching role continues to see it under Needs my attention and on the request lists, whichever option you choose. That is what makes it safe to narrow who gets email. The notifications panel is different: it lists what you were told, so it follows this setting like email does.

Reminders follow the same setting, so a level that notifies two people does not then remind all ten.

Ownership emails go only to the people whose position actually changed. An owner who was already on the work and stayed on it is not told again that it is theirs, and nobody is emailed about their own action.

A missed target is announced and recorded, never enforced. Nothing is rejected, escalated or reassigned because of it, and the request carries on exactly as before.

Approval emails lead with the request's key, so the subject reads [ENV-142] Approval Required: Payments UAT environment. That keeps related mail threaded together and makes a specific request easy to find in a mailbox. The approvals queue shows the same key next to each request title. Some administrative approvals are not raised as requests and have no key; those subjects are unchanged.

---

Approval History

Every workflow instance maintains a full history of decisions:

• Approver name and email
• Decision (Approved, Rejected)
• Decision timestamp
• Decision notes
• Level name

This is visible on the workflow instance detail panel and is also captured in the audit log.

See Audit Logs for the full audit trail reference.

---

Role-Based Access

*Any user can act on a step they are directly and individually assigned to, regardless of role. Provisioners additionally qualify for role-based steps assigned to the PROVISIONER role.

†Attaching or withdrawing an additional form always needs a pending approval step at the workflow's currently active level — assigned to you by name, or matching that level's approver roles. Being an Admin is not enough on its own, and admin override doesn't cover it.

Provisioners see every organisation-wide workflow instance, the same as Admins — the only difference is Admins additionally see each workflow's raw level configuration alongside the instance data.

---

Next Steps

• Manage Bookings
• Environment Requests
• Decommissions
• Additional Forms
• View Audit Logs
• Manage Members