Home / admin / approval-process-apex-patterns

approval-process-apex-patterns

Programmatically driving Salesforce Approval Processes from Apex — `Approval.process(ProcessSubmitRequest)` to submit, `ProcessWorkitemRequest` to approve / reject / reassign, recall semantics, querying `ProcessInstance` and `ProcessInstanceWorkitem` to find pending approvals, and the bulk-submit / bulk-action error-row handling.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-05
• Reliability
• Operational Excellence
• Security

• approval-process
• apex
• process-submit-request
• process-workitem-request
• process-instance
• bulk-approval

Open the skill folder on GitHub

Approval Process Apex Patterns

The platform provides standard approval-process buttons (Submit for Approval, Approve, Reject, Reassign) on record pages. They work for human-driven, single-record approvals. They don't cover:

• Programmatic submission (a scheduled batch creates 1,000 records

  and submits them all for approval).

• Programmatic action (a system event approves / rejects on behalf

  of a user — careful with this one).

• Custom UI (a custom Lightning component that bundles submit +

  status display + approve buttons).

• Querying pending items (which records are awaiting approval, by

  whom, for how long).

This skill covers the Apex API for those cases.

What this skill is NOT. Defining the Approval Process itself (entry criteria, approval steps, approver assignment) is declarative admin work — see admin/approval-processes. The modern Flow-based equivalent (Flow Orchestration with interactive steps assigned to approvers) is a different runtime entirely — see flow/flow-orchestration-patterns.

Before Starting

• Confirm the Approval Process is defined and active. Apex

  references the process by developer name. Check it before you write anything else:

  SELECT Id, DeveloperName, Name, State, TableEnumOrId, LockType
  FROM ProcessDefinition
  WHERE DeveloperName = 'Expense_Approval'

  State must be Active (values: Active, Inactive, Obsolete — Object Reference, ProcessDefinition, object_reference.txt L225341-225426).

• Confirm the submitter is an allowed submitter. "The user must

  be one of the allowed submitters in the process definition setup" (Apex Reference, setSubmitterId, apexrefguide.txt L4021-4024). Setting submitterId to a record owner who isn't in allowedSubmitters fails that row.

• Decide the bulk shape. Approval.process(...) is overloaded

  for a single ProcessRequest or a List<ProcessRequest>, each with an optional allOrNone (apexrefguide.txt L200066-200172). Each call counts as one DML statement against the 150-statement limit, and the records it processes count against the 10,000 records-processed limit (apexdev.txt L19548-19556, L19624).

• Decide the error-row policy. allOrNone = true (default):

  any failure rolls back the whole batch. allOrNone = false: "the remainder of the approval processes can still succeed" (apexrefguide.txt L200119-200123).

Questions to Ask Before Configuring

Ask these before the first new Approval.ProcessSubmitRequest(). Every one of them maps to a row that fails at runtime rather than at compile time.

What a proper implementation adds over just calling Approval.process(req): submissions land in the right process under the right submitter, failed rows are visible and re-drivable instead of silently rolled back, and the approval audit trail says what an auditor expects it to say.

Core Concepts

Request types

Both are passed to Approval.process(...). The call returns a list of Approval.ProcessResult (one per input Request) with success / errors.

ProcessSubmitRequest essentials

Approval.ProcessSubmitRequest req = new Approval.ProcessSubmitRequest();
req.setObjectId(record.Id);
req.setProcessDefinitionNameOrId('Expense_Approval_Process');  // approval process API name
req.setSubmitterId(UserInfo.getUserId());                       // who's "submitting"
req.setComments('Submitting via batch on month-end close');
req.setSkipEntryCriteria(false);                                 // run the entry criteria
Approval.ProcessResult result = Approval.process(req);

Key options:

setSkipEntryCriteria(true) submits a record the admin's criteria were written to exclude. Record why in the calling class, not in a commit message.

ProcessWorkitemRequest essentials

// Find the pending workitem.
ProcessInstanceWorkitem workitem = [
    SELECT Id FROM ProcessInstanceWorkitem
    WHERE ProcessInstance.TargetObjectId = :recordId
      AND ProcessInstance.Status = 'Pending'
    ORDER BY CreatedDate DESC LIMIT 1
];

Approval.ProcessWorkitemRequest req = new Approval.ProcessWorkitemRequest();
req.setWorkitemId(workitem.Id);
req.setAction('Approve');     // 'Approve', 'Reject', 'Removed' (recall), or null + setNextApproverIds for reassign
req.setComments('Approved by system per policy 4.2');
Approval.ProcessResult result = Approval.process(req);

Action values — "Valid values are: Approve, Reject, or Removed. Only system administrators can specify Removed" (apexrefguide.txt L4123-4127):

You rarely need a query to find the workitem you just created. ProcessResult.getNewWorkitemIds() returns "the IDs of the new items submitted to the approval process" (apexrefguide.txt L3795-3801), so a submit-then-approve sequence in the same transaction reads straight from the submit result — this is the shape the Apex Developer Guide's own sample uses (apexdev.txt L20651-20715).

Querying pending approvals

List<ProcessInstance> pending = [
    SELECT Id, TargetObjectId, Status, SubmittedById, ElapsedTimeInDays,
           (SELECT Id, ActorId FROM Workitems)
    FROM ProcessInstance
    WHERE Status = 'Pending'
      AND ProcessDefinition.DeveloperName = 'Expense_Approval'
];

Workitems is the child relationship name for ProcessInstanceWorkitem, and Steps for ProcessInstanceStep (object_reference.txt L226220-226240). Age on ElapsedTimeInDays, not CreatedDate — the field tables for these objects document the elapsed-time fields and do not list CreatedDate.

ProcessInstance is the in-flight approval. ProcessInstanceStep is the audit trail of completed steps. ProcessInstanceWorkitem is the open assignment to a specific approver.

ActorId on both ProcessInstanceStep and ProcessInstanceWorkitem is a polymorphic relationship field that "Refers To Group, User" (object_reference.txt L226648-226670, L226820-226835). A bare Actor.IsActive in the SELECT does not compile; use TYPEOF, and handle the queue case where there is no user at all:

SELECT Id, ActorId, ElapsedTimeInDays, ProcessInstance.TargetObjectId,
       TYPEOF Actor
           WHEN User THEN Username, IsActive
           WHEN Group THEN DeveloperName
       END
FROM ProcessInstanceWorkitem
WHERE ProcessInstance.Status = 'Pending'
  AND ElapsedTimeInDays > 7

ElapsedTimeInDays / InHours / InMinutes are filterable and sortable on both the workitem and the step (object_reference.txt L226836-226878), which is what the stuck-approval audit should age on.

Locking and unlocking

Approval.lock / Approval.unlock / Approval.isLocked set and read the approval lock independently of the process itself. Two constraints worth internalising: "Salesforce admins can edit locked records. Depending on your approval process configuration settings, an assigned approver can also edit locked records", and "Record locks and unlocks are treated as DML. They're blocked before a callout, they count toward your DML limits, and if a failure occurs, they're rolled back along with the rest of your transaction" (apexrefguide.txt L199726-199736). Both take the same optional allOrNothing flag and return LockResult / UnlockResult arrays positionally matched to the input.

Approval.unlock drops the lock. It does not remove the pending approval — the ProcessInstanceWorkitem survives and the approver can still act on it.

Bulk submission

The overload set is process(request), process(request, allOrNone), process(requests), process(requests, allOrNone) (apexrefguide.txt L200066-200172). The guides document no per-call cap on list size; what they do document is that each call is one DML statement (150 per transaction) and that the records it processes count against the 10,000 records-processed-per-transaction limit (apexdev.txt L19548-19556, L19624). UNVERIFIED (2026-09-05): the widely-repeated "200 requests per Approval.process call" figure does not appear in the Apex Reference Guide, the Apex Developer Guide, or the App Limits cheat sheet. Chunking at 200 is still a sound convention — it keeps heap and per-call failure blast radius predictable — but treat it as a design choice, not a documented governor.

Chunk the list anyway, and count DML statements while you do:

List<Approval.ProcessSubmitRequest> requests = ...;
for (Integer i = 0; i < requests.size(); i += 200) {
    Integer end = Math.min(i + 200, requests.size());
    List<Approval.ProcessSubmitRequest> chunk =
        new List<Approval.ProcessSubmitRequest>();
    for (Integer j = i; j < end; j++) chunk.add(requests[j]);
    Approval.ProcessResult[] results = Approval.process(chunk, false);  // allOrNone = false
    for (Integer j = 0; j < results.size(); j++) {
        if (!results[j].isSuccess()) {
            // Log + decide per row
        }
    }
}

allOrNone = false is essential when you have known-bad rows mixed in (e.g. records that don't match entry criteria — those will fail individually rather than killing the whole batch).

Common Patterns

Pattern A — System-initiated batch submission

When to use. Month-end close: identify all expense reports past threshold, submit them all into approval automatically.

public class MonthEndExpenseSubmitter {
    public static void submitOverThreshold() {
        List<Expense__c> toSubmit = [
            SELECT Id FROM Expense__c
            WHERE Status__c = 'Draft'
              AND Total_Amount__c >= 1000
              AND Submitted_Date__c = NULL
        ];

        List<Approval.ProcessSubmitRequest> requests = new List<Approval.ProcessSubmitRequest>();
        for (Expense__c e : toSubmit) {
            Approval.ProcessSubmitRequest req = new Approval.ProcessSubmitRequest();
            req.setObjectId(e.Id);
            req.setProcessDefinitionNameOrId('Expense_Approval');
            req.setSubmitterId(e.OwnerId);  // from the owner, not the running batch user
            req.setComments('Auto-submitted by month-end batch');
            requests.add(req);
        }

        // Bulk submit, allow partial success.
        for (Integer i = 0; i < requests.size(); i += 200) {
            Integer end = Math.min(i + 200, requests.size());
            List<Approval.ProcessSubmitRequest> chunk = new List<Approval.ProcessSubmitRequest>();
            for (Integer j = i; j < end; j++) chunk.add(requests[j]);
            Approval.ProcessResult[] results = Approval.process(chunk, false);
            for (Integer j = 0; j < results.size(); j++) {
                if (!results[j].isSuccess()) {
                    ApplicationLogger.warn(
                        'Submission failed: ' + requests[j].getObjectId() +
                        ' — ' + results[j].getErrors()
                    );
                }
            }
        }
    }
}

Key points: setSubmitterId to the owner (not the batch user), allOrNone = false, log failures rather than abort.

The submitter caveat that bites here: every OwnerId you pass must be an allowed submitter on the process, or that row fails (apexrefguide.txt L4021-4024). If owners are a moving population, either widen allowedSubmitters to <type>owner</type> / <type>allInternalUsers</type> (api_meta.txt L23228-23262) or drop setSubmitterId and submit as one designated service user, and say so in the approval comment.

Pattern B — Auto-approve based on system event

When to use. A downstream system signals approval (e.g. CFO office signs off in an external system; a Platform Event fires; Apex subscriber auto-approves the matching Salesforce expense).

trigger ExpenseApprovedEventSubscriber on Expense_Approved__e (after insert) {
    EventBus.TriggerContext ctx = EventBus.TriggerContext.currentContext();
    for (Expense_Approved__e e : Trigger.new) {
        try {
            ProcessInstanceWorkitem wi = findPendingWorkitem(e.Expense_Id__c);
            if (wi == null) {
                ctx.setResumeCheckpoint(e.ReplayId);
                continue;
            }
            Approval.ProcessWorkitemRequest req = new Approval.ProcessWorkitemRequest();
            req.setWorkitemId(wi.Id);
            req.setAction('Approve');
            req.setComments('Auto-approved by external CFO system; ref ' + e.External_Ref__c);
            Approval.process(req);
            ctx.setResumeCheckpoint(e.ReplayId);
        } catch (Exception ex) {
            ApplicationLogger.error('Auto-approve failed', ex);
            ctx.setResumeCheckpoint(e.ReplayId);
        }
    }
}

Caveat: auto-approval is a security-sensitive action. Audit who can publish the trigger event. The approval-process-step defines who's authorized to approve; programmatic auto-approval bypasses that policy.

Pattern C — Find stuck approvals

When to use. Operational monitoring — surface approvals waiting on inactive users, approvals older than SLA, approvals on deleted source records.

List<ProcessInstanceWorkitem> stuck = [
    SELECT Id, ActorId, ElapsedTimeInDays,
           TYPEOF Actor
               WHEN User THEN Username, IsActive
               WHEN Group THEN DeveloperName
           END,
           ProcessInstance.TargetObjectId, ProcessInstance.Status
    FROM ProcessInstanceWorkitem
    WHERE ProcessInstance.Status = 'Pending'
      AND ElapsedTimeInDays > 7
];

for (ProcessInstanceWorkitem w : stuck) {
    if (w.Actor instanceof User && !((User) w.Actor).IsActive) {
        // Assigned to a deactivated user — reassign.
    } else if (w.Actor instanceof Group) {
        // Assigned to a queue — nobody owns it personally; nudge the queue.
    }
}

Three corrections worth carrying: ActorId is polymorphic over Group and User, so Actor.IsActive needs TYPEOF and a runtime type check; age on ElapsedTimeInDays, which the Object Reference documents as filterable, rather than on CreatedDate, which the ProcessInstanceWorkitem field table does not list (object_reference.txt L226816-226905); and do not test ProcessInstance.TargetObjectId == null as a deleted-record signal — that field is not nillable (object_reference.txt L226147-226160), so it never comes back empty.

Run as a scheduled batch; surface results to admin dashboard or notification channel.

Pattern D — Recall a submission when the source record is invalidated

When to use. Source record changes mid-approval such that the approval should no longer proceed. Example: expense report's amount drops below the threshold that requires VP approval.

Approach. Trigger / flow on the source record detects the invalidating change. Find the pending workitem and recall.

public static void recallApproval(Id recordId, String reason) {
    ProcessInstanceWorkitem wi = [
        SELECT Id FROM ProcessInstanceWorkitem
        WHERE ProcessInstance.TargetObjectId = :recordId
          AND ProcessInstance.Status = 'Pending'
        LIMIT 1
    ];
    Approval.ProcessWorkitemRequest req = new Approval.ProcessWorkitemRequest();
    req.setWorkitemId(wi.Id);
    req.setAction('Removed');  // recall
    req.setComments('Auto-recalled: ' + reason);
    Approval.process(req);
}

Permission note, stated flatly by the Apex Reference: "Only system administrators can specify Removed" (apexrefguide.txt L4123-4127). ApprovalProcess.allowRecall governs the UI equivalent — false means "only administrators can recall approval requests" (api_meta.txt L23094-23097). A recall from an ordinary user's trigger context will fail, so route it: catch the failure and park the record for an admin queue, or run the recall from an async context that executes as a designated admin.

An alternative that needs no admin: reassign instead of recall. ProcessInstanceWorkitem supports update() and ActorId is Updateable (object_reference.txt L226816-226835), so moving the request to a different approver is plain DML.

Decision Guidance

Recommended Workflow

1. Answer the ## Questions to Ask Before Configuring table into templates/approval-process-apex-patterns-template.md. The allowedSubmitters, allowRecall, and adhoc-approver answers decide whether Patterns A and D are even runnable in your context.
2. Read the process definition, don't assume it. Run the ProcessDefinition query from ## Before Starting, then retrieve the approvalProcess metadata (references/metadata-examples.md § "Retrieve, lint, deploy") and read allowedSubmitters, allowRecall, recordEditability, and every step's assignedApprover and whenMultipleApprovers.
3. Deploy the test fixture — the minimal ApprovalProcess XML in references/metadata-examples.md — into a scratch org, so the Apex has something deterministic to submit into. Full declarative design lives in admin/approval-processes, not here.
4. Write the service class from references/metadata-examples.md § "The Apex service class": bulk submit with allOrNone=false and an error-row collector, workitem action via getNewWorkitemIds() or the TYPEOF query, and recall guarded by the admin-only constraint.
5. Lint before you deploy: python3 skills/admin/approval-process-apex-patterns/scripts/check_approval_process_apex_patterns.py --manifest-dir force-app/main/default. It reads approvalProcesses/*.approvalProcess-meta.xml and every .cls / .trigger in the tree, and flags a process name in Apex that no deployed process defines.
6. Write the tests from references/metadata-examples.md § "Test class skeleton": success, mixed-row partial success, the not-an-allowed-submitter failure, and the non-admin recall failure. Assert on ProcessResult.getInstanceStatus() and getErrors(), not just isSuccess().
7. Walk references/gotchas.md and confirm each of the four correction gotchas (5, 7, 8, 11) does not apply to the code you just wrote.

Review Checklist

• [ ] Approval process developer name (not record Id) is referenced in setProcessDefinitionNameOrId, and it is never left null when a specific process is intended.
• [ ] setSubmitterId is set explicitly when running-user-as-submitter is wrong, and every user it can be set to is in the process's allowedSubmitters.
• [ ] setNextApproverIds is passed a single-entry list, and only where a step actually needs it.
• [ ] allOrNone = false for bulk submissions where partial success is acceptable.
• [ ] Approval.ProcessWorkitemRequest finds the workitem via ProcessInstanceWorkitem query, not assumed.
• [ ] Auto-approval pattern (Pattern B) has explicit security review — who can publish the trigger event.
• [ ] Recall pattern (Pattern D) handles permission errors gracefully (some processes restrict recall to admins).
• [ ] Stuck-approval monitoring (Pattern C) runs as a scheduled batch with results surfaced to admins.
• [ ] Any query over ActorId uses TYPEOF and handles the Group (queue) branch.
• [ ] Aging filters use ElapsedTimeInDays / InHours, not CreatedDate.
• [ ] The transaction's Approval.process calls are counted against the 150-DML-statement budget alongside every other DML in the same transaction.
• [ ] python3 scripts/check_approval_process_apex_patterns.py --manifest-dir <dx root> passes, or every finding is triaged.

Salesforce-Specific Gotchas

1. setProcessDefinitionNameOrId accepts the API name; hardcoded record IDs break across orgs. Use API name. (See references/gotchas.md § 1.)
2. Default allOrNone = true rolls back the whole batch on first failure. Bulk submissions need allOrNone = false to preserve successful records. (See references/gotchas.md § 2.)
3. setSubmitterId defaults to the running user. System batches that don't set it explicitly produce approvals "submitted by" the batch service account, not the actual owner. (See references/gotchas.md § 3.)
4. ProcessWorkitemRequest action values are case-sensitive strings — 'Approve' not 'approve'. (See references/gotchas.md § 4.)
5. Recall ('Removed') is documented as system-administrator-only. Not "usually restricted" — the Apex Reference says only sysadmins can specify it. (See references/gotchas.md § 5.)
6. Auto-approval bypasses the approval-process step's "Approver assignment" — the platform records the running user as the approver, not the configured one. Audit implications. (See references/gotchas.md § 6.)
7. The real bulk ceiling is DML, not a 200-request cap. Approval.process burns a DML statement and its rows count toward the 10,000 records-processed limit. (See references/gotchas.md § 7.)
8. setSubmitterId fails for any user not in allowedSubmitters — the batch-submits-as-owner pattern breaks the moment an owner falls outside that list. (See references/gotchas.md § 11.)
9. ActorId is polymorphic over Group and User, so Actor.IsActive needs TYPEOF and a queue-assigned workitem has no user at all. (See references/gotchas.md § 13.)
10. A null processDefinitionNameOrId routes by org process order, and process order is not carried in the metadata across a deploy. (See references/gotchas.md § 14.)

Output Artifacts

Reference Files

Related Skills

• admin/approval-processes — declarative definition of the approval process this skill drives.
• flow/flow-orchestration-patterns — modern multi-stage approval pattern in Flow; consider before reaching for Apex.
• apex/apex-event-bus-subscriber — when system events drive approval actions (Pattern B).
• apex/apex-mocking-and-stubs — for the test class that covers Approval.process() failure modes.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/approval-process-apex-patterns-template.md
• scripts/check_approval_process_apex_patterns.py