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 Information Requests — 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.

---

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 ask for more detail instead of deciding right away — see Information Requests. 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.

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 had a pending Information Request when it timed out, extending returns it to Awaiting Info rather than straight back to Pending.

---

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

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.

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
• Information Requests
• View Audit Logs
• Manage Members