Approval Workflows
Approval workflows add a mandatory review step before data changes become permanent. When an entity has "Requires approval" enabled, edits by regular users are saved as pending changes in a separate staging table. Only after an authorized approver reviews and approves the change does it get committed to the live data.
Three layers:
- Trigger — The entity's "Requires approval" toggle determines whether changes need approval
- Who can approve — A two-step system: role eligibility first, then explicit entity assignment
- Approval flow — Configurable per entity: single-step (one approver) or multi-step chains (multiple approvers in sequence)
How approval rights work:
Approval rights are a two-layer system, completely independent of Read/Write/Moderator permissions:
Layer 1 — Role eligibility
A role has a "Can Approve" checkbox. Any user who belongs to a role with this flag enabled becomes *eligible* to be assigned as an approver. This has nothing to do with which entities that role can read or write — it is purely an eligibility marker.
Layer 2 — Entity assignment
Being eligible is not enough on its own. A user must also be explicitly assigned as an approver for a specific entity. This is managed in Settings → Access Management → Entities tab, or directly in the entity form under Assigned Approvers. Only eligible users (those in a "Can Approve" role) appear in the picker.
Rule: A user can approve an entity when they (a) belong to at least one role with "Can Approve" enabled, *and* (b) have been explicitly added to that entity's Assigned Approvers list. CRUD permissions on the entity are not considered.
What happens when you save:
- User edits cells in the data grid and clicks Save
- If the entity has "Requires approval" → all changes in that save are submitted as a single approval request — the entire batch, not individual records
- A toast confirms: "Changes submitted for approval"
- Every changed record shows a lock icon in the grid — none of them can be edited until the pending request is resolved
- The Notification Bell shows a badge with the pending approval count for approvers
What the grid shows: The data grid always displays the approved (committed) data — pending changes are not mixed into the grid. The only visual change is a small lock icon on rows that have a pending change.
The Approvals screen:
A dedicated page accessible to anyone with approval rights (not admin-only). If you have "Can Approve" on any role, you see this page in the navigation.
The screen shows all pending changes you are authorized to approve:
- Entity name, record Code + Name, change type (Edit / New / Delete)
- Submitted by, submission date, current status
Diff view: Click a pending change to see the detail. A table shows:
| Field | Old value | New value |
|---|---|---|
| Region | Noord-Holland | Zuid-Holland |
| Status | Active | Active |
Changed fields are shown first (sorted by entity attribute order), followed by unchanged fields. This keeps the important information at the top — especially useful for entities with many attributes.
Actions per change:
- Approve — Commits the change to the live data (EntityRows/EntityValues). The pending entry is removed.
- Send back — Sends the submission back to the editor. Use this when the change is *conceptually correct* but something needs fixing — a missing field, wrong value, or unclear note. The editor sees a "Returned" status and can revise and resubmit. The request history is preserved.
- Reject — Permanently closes the submission. Use this when the change *should not proceed at all* — policy violation, budget freeze, wrong entity, or incorrect business decision. The editor is notified with your reason. No revision is expected.
Bulk actions (Approve all / Reject all) are available for processing multiple changes at once.
"My Submissions" tab: Editors can see the status of their own pending changes — pending, approved, rejected, or returned — with the approver's feedback if applicable.
Filters: Filter by model, entity, user, or status to find specific changes quickly.
Record locking:
When a record has a pending change, it is locked for editing until the change is approved, rejected, or returned. Other users see a lock icon and cannot modify the record. This prevents conflicting edits on the same record.
Self-approval:
By default, approvers cannot approve their own submissions (4-eyes principle). This can be toggled per entity via the "Approver may approve own changes" setting in Settings → Access Management → Entities tab. When enabled, approvers can approve changes they submitted themselves.
Example 1 — Simple setup
A "Customers" model with entities "Business Units" and "Contacts". "Business Units" has "Requires approval" enabled.
| Role | Can Approve | Permission |
|---|---|---|
| Data Editors | No | Write on Customers model |
| Quality Reviewers | Yes | Write on "Business Units" only |
User Anna is in both roles.
- Anna edits "Business Units" → change goes to PendingChanges (requires approval)
- Anna edits "Contacts" → change is saved directly (no approval required)
- Anna can approve changes in "Business Units" only (via Quality Reviewers)
- Anna cannot approve her own changes unless "Approver may approve own changes" is enabled on the entity
Example 2 — Multi-model scoping
| Role | Can Approve | Permission |
|---|---|---|
| NL Editors | No | Write on "Customers NL" |
| DE Editors | No | Write on "Customers DE" |
| NL Approvers | Yes | Write on "Customers NL" |
User Bob is in all three roles.
- Bob can edit data in both NL and DE
- Bob can only approve in "Customers NL" — his approval role only has permission there
- Bob cannot approve in "Customers DE" — his DE access comes from "DE Editors" which has no approval rights
Example 3 — Dedicated approval team
| Role | Can Approve | Permission |
|---|---|---|
| All Editors | No | Write on all models |
| Approval Board | Yes | Write on all models |
Only "Approval Board" members can approve. They see all pending changes across all models in their Approvals screen. Editors submit changes and wait for board approval.
Notification Bell integration:
The bell in the top-right header is color-coded by urgency:
- 🔴 Red — one of your submissions was rejected or sent back for revision
- 🟠 Orange — there are pending submissions waiting for your approval
- 🟢 Green — one of your submissions was approved
When multiple states are active simultaneously, the highest-priority color wins (red > orange > green). Clicking the bell opens a dropdown with one entry per category; clicking any entry navigates to the relevant screen and dismisses that badge. The seen baseline persists across page reloads so the bell only rings for new events.
Dashboard widgets:
The home dashboard shows two approval-related widgets:
- Pending Approvals (approvers only) — lists open submissions needing your review, split into "Needs your review" and "Waiting for co-approvers" when the multi-approver strategy is in use
- My Submissions (all users) — shows your own recent submissions and their current status, with a configurable display count
Audit panel integration:
The per-record audit panel (right side of the grid) also shows pending changes for that specific record — who submitted what, current status, and the field-level diff.
Administrator override:
Administrators are not bound by the normal approval chain. Any administrator can use Force approve to push a submission directly to live data at any time — bypassing all approvers, including multi-approver strategy gates.
This is intended for situations where the normal review cycle cannot complete in time: an approver is unavailable, the change is urgent, or the submission was routed incorrectly. Every force approval is permanently logged with the administrator's identity and an optional reason. See Role: Administrator for full details.