Lightweight Multi-Level Approval

For fixed two or three level approval flows (applicant → department → finance), a state machine + approval record table is enough — you do not need a workflow engine.

Design

Concern Approach
Where the state lives On the business entity itself (ApprovalStatus + CurrentLevel), no instance table
Where the history lives One sys_approval_record table, which doubles as the to-do index and the notification target
Who can approve Decided by flow config: org leader / role / specific user / bill field
Concurrency Conditional update on status + level, so double clicks and simultaneous approvals succeed only once
The state machine A pure function in code (ApprovalStateMachine), never persisted, fully unit-testable

Not supported: countersign, parallel branches, conditional routing, jumping back to an arbitrary node. Use a workflow engine (e.g. Elsa) for those.

There is no limit on the number of levels: the flow runs as many nodes as you configure (1 to N, typically 2–3). Once a flow needs conditional routing instead of plain serial levels, that is workflow-engine territory.

Bills in flight follow the level count they were submitted with: changing the flow configuration afterwards (adding or removing a level) no longer changes the number of nodes of the bills that are already running — the level count of that round is stored together with the approval records (SysApprovalRecord.TotalLevels) and a running bill is advanced by it. Bills can therefore no longer get stuck "under approval" because the flow was edited underneath them (legacy rows have a null value and fall back to the snapshot level count, behaving exactly as before).

Two extension points for business modules: the approval extension only owns "who approves and how far" — it never touches business data. When a business module has to write its own data at the very moment the bill is approved (e.g. a purchase receipt posting stock balances), or wants a friendlier failure message for end users, use the two hooks below:

Extension point Interface Purpose
Post action IApprovalPostAction Runs the business write inside the approval transaction when the level is approved
Failure message IApprovalFailureMessageProvider Exposes a readable business message to the end user

Both are optional: when nothing is registered the behavior is exactly the same as if the extension points did not exist (see 6. Post action and 7. Failure message).

States and transition rules

State machine

Draft ──Submit──▶ Level 1 pending ──Approve──▶ Level 2 pending ──Approve──▶ Approved
                        │                             │
                        ├──Reject─────────────────────┴──▶ Rejected ──edit & submit──▶ Level 1 pending (new round)
                        └──Revoke (before anyone approves)─▶ Revoked ──submit───────▶ Level 1 pending (new round)

Pending ──Transfer──▶ same level, only the approver changes
  • Only 5 states: Draft / Pending / Approved / Rejected / Revoked; the level lives in a separate CurrentLevel field
  • Only 5 actions: Submit / Approve / Reject / Revoke / Transfer; the rules are a pure function (ApprovalStateMachine), never persisted, and fully unit-testable
  • Concurrency: every action uses a conditional update on status + level, so a double click or two simultaneous approvals succeed only once; the loser gets "the bill has been handled by someone else, please refresh"

Can the bill still be edited?

State Save changes Delete Notes
Draft Yes, and it stays a draft (no auto-submit by default) Yes Click "Submit for Approval" in the approval tab to enter the flow; see the switch below to restore auto-submit
Pending No — "the bill is under approval and cannot be modified or deleted" No Exception: the current node has "allowEdit": true and the editor is that node's approver
Approved No by default (locked once approved); enable AllowEditAfterApproved to edit, then the re-approval policy applies Yes Default policy is "locked once approved"
Rejected / Revoked Yes, and it is submitted again from level 1 Yes The normal "fix and resubmit" path

Re-approval policy

.AddEasyAdminBlazorApproval(o =>
{
    o.AllowEditAfterApproved = false;   // global default: locked once approved

    o.Flows.Add(new ApprovalFlowConfig
    {
        BillType = typeof(Article).FullName!,
        AllowEditAfterApproved = true,                                      // this bill type stays editable
        ResubmitOnEdit = true,                                             // ...and re-enters approval when edited
        ResubmitFields = [nameof(Article.Title), nameof(Article.Content)],  // but only these count as key fields
        Levels = [ /* see the flow config above */ ]
    });
});

Three settings, each settable globally and overridable per bill type (flow config wins):

Setting Scope Default Meaning
AllowEditAfterApproved global / flow false Whether an approved bill may still be edited; false = locked
ResubmitOnEdit global / flow true If editing is allowed, whether an edit re-enters approval
ResubmitFields flow only empty Key fields that trigger re-approval; empty means any change does

The four common policies map like this:

Policy Configuration
Locked once approved (finance, contracts, inventory) AllowEditAfterApproved = false (default)
Re-approve only when key fields changed AllowEditAfterApproved = true + ResubmitFields = [key fields]
Always re-approve on any edit AllowEditAfterApproved = true, ResubmitFields empty
Edits take effect immediately AllowEditAfterApproved = true + ResubmitOnEdit = false

How key fields are compared: on submit, the values of the configured fields are sorted by name, concatenated and hashed with SHA256; the hash is stored on that round's start record (sys_approval_record.ResubmitHash). On the next save the hash is recomputed and compared — if nothing changed, approval is skipped. Only the hash is stored, never the values themselves. After changing ResubmitFields, the old hash no longer matches, so the next save is treated as a change (the safe direction).

Re-approval by amount/risk tier (small amounts skip approval, large ones go through the full flow) is flow routing and out of scope for this extension.

Rounds

Resubmitting after a rejection/revoke, or editing an approved bill, starts a new round:

  • The timeline is ordered by round then level; nodes in round 2+ are prefixed with "Round 2 ·"
  • Records of earlier rounds are kept in full (audit requirement)

Separating save from submit

Saving and submitting are separate by default: saving only saves (the bill stays a draft); it enters the flow when the user clicks Submit for Approval in the business page's approval tab. This matches the usual OA workflow (fill in → review → submit).

To make saving submit automatically:

.AddEasyAdminBlazorApproval(o =>
{
    o.AutoSubmitOnSave = true;                 // global default: submit right after saving

    o.Flows.Add(new ApprovalFlowConfig
    {
        BillType = typeof(Article).FullName!,
        AutoSubmitOnSave = true,               // or enable it for one bill type only (flow config wins)
        Levels = [ /* ... */ ]
    });
});

With auto-submit off, the user triggers the submission; IApprovalService.CanSubmitAsync(billType, status) tells the UI whether that state can be submitted (used to show/hide the button), and SubmitAsync re-validates on the server.

1. Install

dotnet add package EasyAdminBlazor.Approval
builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions { ... })
       .AddEasyAdminBlazorApproval(o =>
       {
           o.Flows.Add(new ApprovalFlowConfig
           {
               BillType = typeof(Article).FullName!,
               Levels =
               [
                   new ApprovalLevelConfig { Level = 1, Name = "Department manager", Kind = ApproverKind.OrgLeader, Offset = 1 },
                   new ApprovalLevelConfig { Level = 2, Name = "Finance review", Kind = ApproverKind.Role, Value = "Finance" }
               ]
           });
       });

The sys_approval_record table is created automatically.

2. Put a business entity under approval

public partial class Article : ApprovalEntityFull   // with soft delete
{
    // existing members unchanged
}

public partial class Order : ApprovalEntity { }     // without soft delete

If the entity already inherits another base class, implement IApprovalBill and declare the two fields yourself:

public class MyBill : EntityCreated, IApprovalBill
{
    [Column(Position = -8)] public ApprovalStatus ApprovalStatus { get; set; }
    [Column(Position = -7)] public int CurrentLevel { get; set; }
}

The interface is the contract used by the components and the engine; the fields still have to be declared by the entity or base class, because interface members do not become database columns.

Submitter and submit time reuse EntityCreated.CreatedUserId / CreatedTime.

3. Wire up a page

Option 1: let AdminTable take over (recommended). Any entity implementing IApprovalBill will:

  • submit for approval right after a successful save (bill types without flow config are unaffected)
  • be blocked from edit/delete while pending
  • get an approval status column in the grid (ApprovalStatusText)

Option 2: use the panel component.

@using EasyAdminBlazor.Approval.Components

<ApprovalActions TItem="Article" Bill="Model" OnChanged="Reload" />

It shows the approve / reject / revoke buttons based on the current state and the signed-in user, plus the full approval timeline.

Option 3: call the service. Inject IApprovalService and use SubmitAsync / ApproveAsync / RejectAsync / RevokeAsync / TransferAsync. All return ApprovalSubmitResult; when Submitted is false, Message tells you why.

4. Approver sources

Kind Description Value / Field
OrgLeader Org leader, walking up from the submitter's org via SysOrg.ResponsibleUserId Offset: 1 = own org, 2 = parent org
Role All enabled users of a role (any one of them can approve) Value = role name
User A specific user Value = user id
FormField Value of a bill property Field = property name

Resolved users must exist and be enabled, otherwise submission fails with "no approver found for ..." instead of creating an orphan to-do.

Approvers are resolved once at submit time, so use transfer instead of editing the config when someone is unavailable.

Self-approval is disabled by default. The submitter is skipped while resolving approvers:

  • OrgLeader: if a level's responsible user is the submitter (common in one-person departments), the walk continues upward instead of assigning it to the submitter
  • Role / FormField: the submitter is removed from the list; if that leaves nobody, submission fails with "no approver found for ..." — a sign the org/role setup is incomplete

When self-approval is genuinely needed (a department with a single person), set ApprovalOptions.AllowSelfApproval = true.

5. Approval Center

The framework ships a top-level menu Approval Center (/Admin/ApprovalTodo, page lives in the core project at EasyAdminBlazor/Pages/ApprovalTodo.razor). Install the extension and grant the menu — no page to write yourself.

One menu, four views (no extra sub-menus):

View Content
My To-do IsCurrent, Pending, approver = me; disappears as soon as you approve or reject
Handled Nodes I actually acted on (approved / rejected / transferred) — what did I sign, and what did I write
My Requests Every round I submitted — "where is my bill stuck". One row per round: the node column shows the round's current pending node (in approval) or the last handled node (finished, e.g. "Revoke"), the status column shows the round result (pending / approved / rejected / revoked), and the approver + time belong to that node
All Every approval record — administrators only

Every view supports keyword search on the bill title, filtering by node result (pending / approved / rejected / transferred / skipped …) and paging.

Clicking a row shows the bill content (rendered automatically from the entity's fields and DisplayName, long text truncated), the current approval status and the full timeline (grouped by round) on the right. In My To-do you can type a comment and approve/reject directly, and the list refreshes afterwards; the other views are read-only.

In My Requests, selecting a bill you submitted that nobody has approved yet shows a Revoke button (revoke, fix it, and submit again as a new round).

The menu is provisioned automatically, including in existing projects. A brand-new database gets it from the framework seed; for existing projects (whose menu table is not empty, so the seed does nothing) the extension creates it at startup — no manual menu setup. Disable with ApprovalOptions.AutoCreateMenu = false. Earlier versions used "Approval Center (group) + My To-do (child)". They are now merged into a single top-level menu; the upgrade runs automatically at startup and keeps the original menu id, so role grants are preserved. An auto-created menu is visible to administrators only until you grant it to other roles in role management.

The to-do data itself is a single-table query and can be used from your own pages:

var todos = await approvalService.GetTodoListAsync();   // my to-do (entities)
var count = await approvalService.GetTodoCountAsync();

await approvalService.ApproveByBillTypeAsync(record.BillType, record.BillId, "ok");
await approvalService.RejectByBillTypeAsync(record.BillType, record.BillId, "missing documents");

Button permissions

Approve / Reject / Revoke in the Approval Center use the framework's button-level permissions (SysMenu button paths: approve / reject / revoke). The menu seed already contains these three buttons — tick them when granting the Approval Center menu to a role; administrators always pass.

  • UI: the button is hidden when the user lacks the permission
  • Service: ApprovalService re-checks the same permission, so calling the API directly is rejected too ("no permission to perform this operation")
  • The <ApprovalActions> panel inside business pages obeys the same rules

The approval tab inside the business edit dialog serves a different case: when the current node sets allowEdit, the approver has to edit the bill first and then approve it.

6. Post action (IApprovalPostAction)

The approval extension owns the flow, not your business data. To make "the bill is approved" and "the business data is written" one single database commit (e.g. writing stock balances and stock transactions when a purchase receipt is approved), implement IApprovalPostAction and register it.

The interface lives in Core (EasyAdminBlazor.Core/Approval/IApprovalPostAction.cs, namespace EasyAdminBlazor), so a business module only depends on Core and is not coupled to the approval extension at compile time:

public interface IApprovalPostAction
{
    Task ExecuteAsync(ApprovalPostActionContext context);
}

ApprovalPostActionContext exposes:

Member Description
Bill The business bill instance (implements IApprovalBill)
BillType / BillId Bill type identifier (entity full name) and Id
Transaction The work unit of the current approval transaction (IApprovalUnitOfWork) — take repositories from it so the write joins the approval transaction
UserId / UserName The user who performed the approval operation

Registration and implementation:

builder.Services.AddScoped<IApprovalPostAction, InventoryApprovalPostAction>();
public sealed class InventoryApprovalPostAction : IApprovalPostAction
{
    public Task ExecuteAsync(ApprovalPostActionContext context)
    {
        // Only repositories from context.Transaction join the approval transaction
        var repo = context.Transaction.GetRepository<StockBalance>();
        // ... write the business data
        return Task.CompletedTask;
    }
}

Rules:

  • Only write to the database inside the hook — no HTTP calls and no messages, they would lengthen the transaction. Send notifications after the commit instead.
  • Only take repositories from context.Transaction. Opening your own transaction breaks atomicity; IApprovalUnitOfWork deliberately offers just GetRepository<TEntity>() to close that hole.
  • If the hook throws, the whole approval transaction rolls back: the approval state does not advance, no approval record is written and no business data is written.
  • When it runs: only when the current level is Approved and the round ends, inside the approval transaction, for every registered hook in turn. A rejection never triggers it.
  • With no hook registered the approval extension behaves exactly as before.

7. Failure message (IApprovalFailureMessageProvider)

When approval processing fails, the framework shows a generic message by default: "Approval processing failed, please try again later. TraceId: xxx" (no exception details leak). If a business module can translate the exception into something an end user understands (e.g. "not enough stock: 64 available in warehouse 'Main', 100 requested"), implement this hook.

The interface also lives in Core (EasyAdminBlazor.Core/Approval/IApprovalFailureMessageProvider.cs):

public interface IApprovalFailureMessageProvider
{
    /// <summary>A readable message for the end user; return null to fall back to the generic message.</summary>
    string? Resolve(Exception exception, string? billType);
}

Registration and implementation:

builder.Services.AddScoped<IApprovalFailureMessageProvider, InventoryApprovalFailureMessageProvider>();
public sealed class InventoryApprovalFailureMessageProvider : IApprovalFailureMessageProvider
{
    public string? Resolve(Exception exception, string? billType)
        => exception is InventoryBusinessException biz ? biz.Message : null;
}

Rules:

  • Only handle the exceptions you understand; return null for anything else so the framework falls back to the generic message — technical details (SQL, stack traces) never reach the end user.
  • When it matches, the final message looks like Not enough stock: 64 available in warehouse 'Main', 100 requested (TraceId: 9512c427c3324c18) — the TraceId is still appended, so support can find the entry in the system log.
  • An exception thrown by the hook itself does not break the approval flow: the framework logs it and asks the next hook, and falls back to the generic message when none matches.
  • With no hook registered the behavior is exactly the same as before.

8. Options

  • Notification: on submit and on a level change an in-app message is sent through AdminMessageService and pushed over SignalR; switch it off with ApprovalOptions.EnableNotification = false.
  • Config changes without a restart: see the next section, the flow can be changed under "System Management → Configuration", which takes precedence over the default flow in code.
  • Editing while the bill is in approval: set AllowEdit on the node to true; only the approver of that node may then edit the bill.
  • Re-approval after a change: see "Re-approval policy" above, three levels are configurable, the default is "locked after approval".
  • A comment is mandatory: RequireCommentOnReject (default true), RequireCommentOnApprove (default false).
  • Saving and submitting: separate by default (saving keeps the bill in draft, it enters the flow when the user clicks "Submit for approval"); ApprovalOptions.AutoSubmitOnSave = true restores "submit on save", and it can also be enabled per bill type.
  • Localization: the approval page, the approval panel, the status texts and all service messages go through the language packs. Approval-specific text and the EasyAdminBlazor.ApprovalTodoItem entity block live in Extensions/EasyAdminBlazor.Approval/Locales/{culture}.json and are merged into CommonLocalizer when the extension is registered. Keys shared with the framework or other extensions stay in the EasyAdminBlazor.Common block of EasyAdminBlazor/Locales/{culture}.json. To add another culture, translate both places (see Localization). Property names of your own entities (for example the "approval status" column) still live in your project's Locales/{culture}.json, keyed by entity full name → property name, as usual.

Options (ApprovalOptions; a flow config with the same name overrides the global default):

Option Default Meaning
EnableNotification true Send an in-app message (plus SignalR push) on submit and level change
AllowEditAfterApproved false Whether an approved bill may still be edited; false = locked after approval
AutoSubmitOnSave false Submit automatically after saving; false = saving and submitting stay separate
ResubmitOnEdit true Whether an edit re-enters approval (only relevant when editing is allowed)
RequireCommentOnReject true A comment is mandatory when rejecting
RequireCommentOnApprove false A comment is mandatory when approving
AllowRevoke true The submitter can revoke while nobody has approved yet
AllowSelfApproval false The submitter may approve their own bill (by default the submitter is skipped)
AutoCreateMenu true Create the "Approval Center" menu on startup
Enabled true Master switch of the extension

9. Configuring the flow from the admin UI

No code required — add one config item under System Management → Configuration:

Field Value
Name Anything, e.g. "Article approval flow" (for identification only)
Unique Code APPROVAL_FLOW_Article
Value the JSON below
{
  "enabled": true,
  "allowEditAfterApproved": true,
  "resubmitOnEdit": true,
  "resubmitFields": [ "Title", "Content" ],
  "levels": [
    { "level": 1, "name": "Department manager", "kind": "OrgLeader", "offset": 1 },
    { "level": 2, "name": "Finance review", "kind": "Role", "value": "Finance" },
    { "level": 3, "name": "General manager", "kind": "User", "value": "838392596680773" }
  ]
}
Field Meaning
enabled Whether approval is enabled for this bill type
allowEditAfterApproved Whether an approved bill may still be edited; omitted = global default (false = locked)
autoSubmitOnSave Whether saving submits for approval automatically; omitted = global default (false = save and submit are separate)
resubmitOnEdit If editing is allowed, whether an edit re-enters approval; omitted = global default (true)
resubmitFields Key fields that trigger re-approval; omitted or empty = any change triggers it
level Level number starting at 1; omit it and the array order is used
name Node name, shown in the to-do list and the approval timeline
kind OrgLeader / Role / User / FormField
value role name for Role, user id for User
offset OrgLeader only: 1 = own org leader, 2 = parent org leader
field FormField only: which property supplies the approver
allowEdit whether this node's approver may also edit the bill (default false)

Use the short type name in the code (APPROVAL_FLOW_Article, not APPROVAL_FLOW_EasyAdminBlazor.Demo.Blog.Article). The unique-code column is only 30 characters, and a full type name overflows it (MySQL truncates, and the config is then never found). Lookup order is: full name first, then short name.

Changes take effect immediately, no restart needed. Config in the database takes precedence over the code default.

10. Troubleshooting

"No approver found for «level»" — the level resolved to nobody: check that the org has a responsible user, the role has enabled users, or the configured user still exists.

The bill cannot be edited anymore — bills under approval are read-only by default. Revoke/reject it first, or set AllowEdit = true on the current node.

A module should not use approval — simply do not configure a flow for that bill type, or set ApprovalFlowConfig.Enabled = false.

The approver left the company — the current approver or an administrator can transfer the to-do to somebody else.

I can see the timeline but not the buttons — the signed-in user is neither the approver of the current node nor an administrator.

The business write fails while approving — what does the user see? By default: "Approval processing failed, please try again later. TraceId: xxx"; the real cause is in the system log (search by TraceId). When the business module registers the failure message hook, the user sees the readable business message directly (e.g. "Not enough stock: 64 available in warehouse 'Main', 100 requested"). In both cases the whole approval transaction rolls back — the approval state does not advance, no approval record is written, no business data is written, and the bill can be approved again.

I want the approval to write business data Implement the IApprovalPostAction post action: it runs your write inside the approval transaction, so a failed write also stops the approval from advancing.