PranavNagrecha/AwesomeSalesforceSkills / skills/admin/approval-process-apex-patterns
approval-process-apex-patterns
VerifiedProgrammatically 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. Covers when to use Apex-driven approval (system-initiated submission, batch approvals, custom UIs) vs leaving the platform's standard buttons in place. NOT for the Approval Process metadata definition itself (that's admin / declarative — see admin/approval-processes), NOT for Flow-based approvals (use flow/flow-orchestration-patterns).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 32.1 KB |
| references/examples.md | markdown | 9.5 KB |
| references/gotchas.md | markdown | 20.5 KB |
| references/llm-anti-patterns.md | markdown | 9.1 KB |
| references/metadata-examples.md | markdown | 20.8 KB |
| references/well-architected.md | markdown | 7.6 KB |
| scripts/check_approval_process_apex_patterns.pyexecutable | script | 20.1 KB |
| templates/approval-process-apex-patterns-template.md | markdown | 3.0 KB |
references/metadata-examples.md
View on GitHub# Metadata Examples — Approval Process Apex Patterns
This file gives an Apex-driven approval implementation something
deterministic to run against: a **minimal, deployable test-fixture**
`ApprovalProcess`, the service class that drives it, the queries that
inspect it, and the test class that proves the failure modes.
It is deliberately not a declarative design guide. Element names,
enum values, and the skeleton come from the Metadata API Developer
Guide `ApprovalProcess` section (api_meta.txt L23057-23659); the full
multi-step design treatment — entry criteria, approver routing,
workflow actions, email templates — belongs to
`skills/admin/approval-processes/references/metadata-examples.md`.
Read that one when you are designing the process. Read this one when
you are writing the Apex.
Lint the tree before deploying:
```bash
python3 skills/admin/approval-process-apex-patterns/scripts/check_approval_process_apex_patterns.py \
--manifest-dir force-app/main/default
```
---
## Where the files live
| Type | package.xml `<name>` | File in a DX project | API |
|---|---|---|---|
| Approval process | `ApprovalProcess`, member `<Object>.<Name>` | `approvalProcesses/Expense__c.Expense_Approval.approvalProcess-meta.xml` | 28.0+ |
| Service class | `ApexClass` | `classes/ExpenseApprovalService.cls` | — |
| Test class | `ApexClass` | `classes/ExpenseApprovalServiceTest.cls` | — |
The guide states only that `ApprovalProcess` components "have the
suffix `.approvalProcess` and are stored in the `approvalProcesses`
folder" (api_meta.txt L23072-23073). UNVERIFIED (2026-09-05): the
object-qualified `<Object>.<Name>` filename is not spelled out in the
guide; it is inferred from the guide's wildcard note, which rejects
`Lead.*` as a way to retrieve a subset (api_meta.txt L23655-23659) —
a restriction that only makes sense if the member name is
object-qualified. If a retrieve in your org produces a different
filename, trust the retrieve.
---
## The test-fixture approval process
Everything in this fixture exists to make Apex behaviour observable,
and each choice maps to a question the Apex has to answer:
- **`<active>true</active>`** — required field. The `ProcessDefinition`
preflight query below asserts `State = 'Active'`; an inactive
process is invisible to a submission that names it.
- **`<allowRecall>true</allowRecall>`** — with `false`, "only
administrators can recall approval requests" (api_meta.txt
L23094-23097). True is what lets the recall test distinguish an
Apex permission failure from a process-configuration one.
- **`<allowedSubmitters><type>allInternalUsers</type>`** — required
field. `allInternalUsers` is "all Salesforce users in the
organization" (api_meta.txt L23261), which is what makes
`setSubmitterId(anyUser.Id)` succeed in a test. A production
process should be narrower — and that narrowness is exactly what
breaks the batch-submits-as-owner pattern (gotcha 11).
- **`<entryCriteria>`** — one filter, so `setSkipEntryCriteria(true)`
and `false` produce visibly different outcomes.
- **Two steps, `Unanimous` on the second** — so the test can observe
the other approver's `StepStatus` flipping to `NoResponse` on a
rejection (object_reference.txt L226753-226766).
- **`<recordEditability>AdminOrCurrentApprover</recordEditability>`** —
the wider of the two values, so a test approver can edit the locked
record. `AdminOnly` restricts editing to Modify All Data / Modify
All Records holders (api_meta.txt L23180-23196).
- **No workflow actions at all** — `initialSubmissionActions` and
friends are `WorkflowActionReference` pointers resolved against the
object's workflow file at deploy time. Omitting them keeps the
fixture a single deployable file.
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ApprovalProcess xmlns="http://soap.sforce.com/2006/04/metadata">
<active>true</active>
<allowRecall>true</allowRecall>
<!-- Required. Widest possible, so setSubmitterId never fails in a
fixture. Production processes narrow this - see gotcha 11. -->
<allowedSubmitters>
<type>allInternalUsers</type>
</allowedSubmitters>
<approvalPageFields>
<field>Name</field>
<field>Owner</field>
<field>Total_Amount__c</field>
</approvalPageFields>
<!-- STEP 1: adhoc approver. The submitter supplies the approver,
which is what setNextApproverIds is for. No rejectBehavior is
allowed on the first step. -->
<approvalStep>
<allowDelegate>false</allowDelegate>
<assignedApprover>
<approver>
<type>adhoc</type>
</approver>
</assignedApprover>
<description>Approver supplied by the submitting Apex.</description>
<label>Nominated Approver</label>
<name>Nominated_Approver</name>
</approvalStep>
<!-- STEP 2: two named approvers, unanimous. Entered only above
5000, so a fixture record can be steered into one step or two. -->
<approvalStep>
<allowDelegate>false</allowDelegate>
<assignedApprover>
<approver>
<name>finance.a@example.com</name>
<type>user</type>
</approver>
<approver>
<name>finance.b@example.com</name>
<type>user</type>
</approver>
<whenMultipleApprovers>Unanimous</whenMultipleApprovers>
</assignedApprover>
<entryCriteria>
<criteriaItems>
<field>Expense__c.Total_Amount__c</field>
<operation>greaterThan</operation>
<value>5000</value>
</criteriaItems>
</entryCriteria>
<ifCriteriaNotMet>ApproveRecord</ifCriteriaNotMet>
<label>Finance Pair</label>
<name>Finance_Pair</name>
<rejectBehavior>
<type>RejectRequest</type>
</rejectBehavior>
</approvalStep>
<!-- Entry criteria for the process itself. setSkipEntryCriteria(true)
is what bypasses this - and only when the process is named. -->
<entryCriteria>
<criteriaItems>
<field>Expense__c.Total_Amount__c</field>
<operation>greaterOrEqual</operation>
<value>1000</value>
</criteriaItems>
</entryCriteria>
<enableMobileDeviceAccess>false</enableMobileDeviceAccess>
<finalApprovalRecordLock>false</finalApprovalRecordLock>
<finalRejectionRecordLock>false</finalRejectionRecordLock>
<label>Expense Approval</label>
<recordEditability>AdminOrCurrentApprover</recordEditability>
<showApprovalHistory>true</showApprovalHistory>
</ApprovalProcess>
```
`enableMobileDeviceAccess` must stay `false` here: "If set to true,
approval steps can't have approvers of type `adhoc`" (api_meta.txt
L23127-23129), and step 1 is `adhoc` on purpose.
---
## The Apex service class
Bulk submit with an error-row collector, workitem action without a
follow-up query, and a recall that expects to be refused.
```apex
/**
* Drives the Expense_Approval process. Deployable against the
* fixture ApprovalProcess in this file.
*/
public with sharing class ExpenseApprovalService {
/** Chunk size. Not a documented governor - see gotchas.md § 7. */
@TestVisible private static Integer CHUNK = 200;
public class Failure {
public Id recordId;
public String message;
public Failure(Id recordId, String message) {
this.recordId = recordId;
this.message = message;
}
}
/**
* Submits each record on behalf of its owner, allowing partial
* success. Returns one Failure per row that did not submit.
*/
public static List<Failure> submit(List<Expense__c> records, Id approverId) {
List<Approval.ProcessSubmitRequest> requests =
new List<Approval.ProcessSubmitRequest>();
for (Expense__c e : records) {
Approval.ProcessSubmitRequest req = new Approval.ProcessSubmitRequest();
req.setObjectId(e.Id);
// Developer name, never a 300-prefixed record Id.
req.setProcessDefinitionNameOrId('Expense_Approval');
// Must be an allowedSubmitter on the process definition.
req.setSubmitterId(e.OwnerId);
req.setComments('Auto-submitted by ExpenseApprovalService');
// Step 1 is adhoc. Exactly one Id, never more.
if (approverId != null) {
req.setNextApproverIds(new List<Id>{ approverId });
}
requests.add(req);
}
List<Failure> failures = new List<Failure>();
for (Integer i = 0; i < requests.size(); i += CHUNK) {
Integer stop = Math.min(i + CHUNK, requests.size());
List<Approval.ProcessSubmitRequest> chunk =
new List<Approval.ProcessSubmitRequest>();
for (Integer j = i; j < stop; j++) {
chunk.add(requests[j]);
}
// Each call is ONE DML statement against the 150 limit.
Approval.ProcessResult[] results = Approval.process(chunk, false);
for (Integer j = 0; j < results.size(); j++) {
if (!results[j].isSuccess()) {
failures.add(new Failure(
(Id) chunk[j].getObjectId(),
describe(results[j].getErrors())
));
}
}
}
return failures;
}
/**
* Submits and immediately approves in the same transaction.
* getNewWorkitemIds() removes the need to re-query the workitem.
*/
public static Approval.ProcessResult submitAndApprove(Id recordId, Id approverId) {
Approval.ProcessSubmitRequest submitReq = new Approval.ProcessSubmitRequest();
submitReq.setObjectId(recordId);
submitReq.setProcessDefinitionNameOrId('Expense_Approval');
submitReq.setNextApproverIds(new List<Id>{ approverId });
Approval.ProcessResult submitted = Approval.process(submitReq, false);
if (!submitted.isSuccess()) {
return submitted;
}
List<Id> newWorkitems = submitted.getNewWorkitemIds();
if (newWorkitems.isEmpty()) {
return submitted;
}
Approval.ProcessWorkitemRequest actionReq =
new Approval.ProcessWorkitemRequest();
actionReq.setWorkitemId(newWorkitems[0]);
actionReq.setAction('Approve'); // Approve | Reject | Removed
actionReq.setComments('Auto-approved under policy 4.2');
return Approval.process(actionReq, false);
}
/**
* Reassigns a pending request. Plain DML on ProcessInstanceWorkitem
* - no administrator permission required, unlike a recall.
*/
public static void reassign(Id workitemId, Id newActorId) {
update new ProcessInstanceWorkitem(Id = workitemId, ActorId = newActorId);
}
/**
* Recalls. 'Removed' is system-administrator-only, so this is
* written to be refused, not to be assumed.
*/
public static Boolean recall(Id workitemId, String reason) {
Approval.ProcessWorkitemRequest req = new Approval.ProcessWorkitemRequest();
req.setWorkitemId(workitemId);
req.setAction('Removed');
req.setComments('Recalled: ' + reason);
try {
Approval.ProcessResult result = Approval.process(req, false);
return result.isSuccess();
} catch (Exception ex) {
// Non-admin context. Park it rather than swallowing it.
System.debug(LoggingLevel.WARN, 'Recall refused: ' + ex.getMessage());
return false;
}
}
private static String describe(Database.Error[] errors) {
List<String> parts = new List<String>();
for (Database.Error err : errors) {
parts.add(err.getStatusCode() + ': ' + err.getMessage());
}
return String.join(parts, ' | ');
}
}
```
---
## Pending approvals per user
The one query an operations dashboard actually needs: everything a
given approver is sitting on, aged, with the queue case separated
out. `ActorId` is polymorphic over `Group` and `User`
(object_reference.txt L226820-226835), so it needs `TYPEOF`.
```sql
SELECT Id,
ActorId,
ElapsedTimeInDays,
ElapsedTimeInHours,
ProcessInstance.TargetObjectId,
ProcessInstance.Status,
ProcessInstance.SubmittedById,
ProcessInstance.ProcessDefinition.DeveloperName,
TYPEOF Actor
WHEN User THEN Username, IsActive, Name
WHEN Group THEN DeveloperName, Type
END
FROM ProcessInstanceWorkitem
WHERE ProcessInstance.Status = 'Pending'
ORDER BY ElapsedTimeInDays DESC
```
Swap the filter for `ActorId = :someUserId` to scope it to one
approver, or add `AND ElapsedTimeInDays > 7` for the SLA-breach
sweep. Age on `ElapsedTimeInDays`, which the Object Reference
documents as Filter/Sort on this object (object_reference.txt
L226836-226846).
The completed-history counterpart, for the audit report:
```sql
SELECT Id, StepStatus, Comments, ActorId, OriginalActorId, ElapsedTimeInDays
FROM ProcessInstanceStep
WHERE ProcessInstanceId IN (
SELECT Id FROM ProcessInstance WHERE TargetObjectId = :recordId
)
ORDER BY ElapsedTimeInDays DESC
```
`StepStatus` carries the same nine values as `ProcessInstance.Status`
— Approved, Fault, Held, NoResponse, Pending, Reassigned, Rejected,
Removed, Started (object_reference.txt L226748-226766). Filtering
that report on `StepStatus = 'Rejected'` undercounts: on a unanimous
step, one rejection sets every *other* approver's step to
`NoResponse`.
---
## Test class skeleton
The four cases that matter are the three failures plus the happy
path. Nothing here mocks `Approval.process` — it runs for real
against the deployed fixture.
```apex
@IsTest
private class ExpenseApprovalServiceTest {
@TestSetup
static void setup() {
// TestDataFactory: see templates/apex/tests/TestDataFactory.
List<Expense__c> expenses = new List<Expense__c>();
for (Integer i = 0; i < 3; i++) {
expenses.add(new Expense__c(
Name = 'E-' + i,
Total_Amount__c = 2000 // above the 1000 entry criterion
));
}
// One row deliberately BELOW entry criteria - the mixed batch.
expenses.add(new Expense__c(Name = 'E-low', Total_Amount__c = 10));
insert expenses;
}
@IsTest
static void submitsBulkWithPartialSuccess() {
List<Expense__c> all = [SELECT Id, OwnerId FROM Expense__c];
Id approver = UserInfo.getUserId();
Test.startTest();
List<ExpenseApprovalService.Failure> failures =
ExpenseApprovalService.submit(all, approver);
Test.stopTest();
// allOrNone=false: the three valid rows submitted anyway.
Assert.areEqual(1, failures.size(),
'Only the below-threshold row should fail');
Assert.areEqual(3,
[SELECT COUNT() FROM ProcessInstance WHERE Status = 'Pending'],
'The three qualifying rows are pending');
}
@IsTest
static void reportsInstanceStatusNotJustSuccess() {
Expense__c e = [SELECT Id FROM Expense__c WHERE Total_Amount__c = 2000 LIMIT 1];
Test.startTest();
Approval.ProcessResult result =
ExpenseApprovalService.submitAndApprove(e.Id, UserInfo.getUserId());
Test.stopTest();
Assert.isTrue(result.isSuccess(), 'Approve should succeed');
// Assert on the status, not only the boolean.
Assert.areEqual('Approved', result.getInstanceStatus(),
'Single-step approval completes the instance');
}
@IsTest
static void rejectsSubmitterOutsideAllowedSubmitters() {
// Only meaningful against a process whose allowedSubmitters is
// narrower than allInternalUsers. Point this at the production
// process name, not the fixture, to exercise gotcha 11.
User outsider = TestUserFactory.createUser('Standard User', new List<String>());
Expense__c e = [SELECT Id FROM Expense__c WHERE Total_Amount__c = 2000 LIMIT 1];
e.OwnerId = outsider.Id;
Test.startTest();
List<ExpenseApprovalService.Failure> failures =
ExpenseApprovalService.submit(new List<Expense__c>{ e }, UserInfo.getUserId());
Test.stopTest();
Assert.areEqual(1, failures.size(),
'A submitter outside allowedSubmitters fails its row');
}
@IsTest
static void recallIsRefusedForNonAdmin() {
Expense__c e = [SELECT Id, OwnerId FROM Expense__c WHERE Total_Amount__c = 2000 LIMIT 1];
ExpenseApprovalService.submit(new List<Expense__c>{ e }, UserInfo.getUserId());
ProcessInstanceWorkitem wi = [
SELECT Id FROM ProcessInstanceWorkitem
WHERE ProcessInstance.TargetObjectId = :e.Id
LIMIT 1
];
User standard = TestUserFactory.createUser('Standard User', new List<String>());
Boolean recalled;
Test.startTest();
System.runAs(standard) {
recalled = ExpenseApprovalService.recall(wi.Id, 'amount corrected');
}
Test.stopTest();
Assert.isFalse(recalled,
'Only system administrators can specify the Removed action');
}
}
```
`TestUserFactory.createUser(profileName, permissionSetNames)` and
`TestDataFactory` are the repo's shared fixtures under
`templates/apex/tests/` — do not hand-roll new ones.
---
## package.xml
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
<types>
<members>Expense__c.Expense_Approval</members>
<name>ApprovalProcess</name>
</types>
<types>
<members>ExpenseApprovalService</members>
<members>ExpenseApprovalServiceTest</members>
<name>ApexClass</name>
</types>
<types>
<members>Expense__c</members>
<name>CustomObject</name>
</types>
<version>62.0</version>
</Package>
```
The wildcard `*` under `ApprovalProcess` retrieves every approval
process for every object; "you can't use it to retrieve a subset.
Syntax such as `Lead.*` isn't supported" (api_meta.txt L23655-23659).
---
## Retrieve, lint, deploy
```bash
# 1. Read what the org actually has before writing any Apex against it.
sf project retrieve start \
--metadata "ApprovalProcess:Expense__c.Expense_Approval" \
--target-org myorg
# 2. Lint the tree - checks the fixture XML and every .cls that names a process.
python3 skills/admin/approval-process-apex-patterns/scripts/check_approval_process_apex_patterns.py \
--manifest-dir force-app/main/default
# 3. Validate without committing, running only this skill's tests.
sf project deploy validate \
--manifest manifest/package.xml \
--test-level RunSpecifiedTests \
--tests ExpenseApprovalServiceTest \
--target-org myorg
# 4. Deploy.
sf project deploy start \
--manifest manifest/package.xml \
--test-level RunSpecifiedTests \
--tests ExpenseApprovalServiceTest \
--target-org myorg
```
The approval process is deployed `<active>true</active>` here because
it is a fixture. A production process should deploy inactive and be
activated after its workflow actions and templates exist — and, per
the Metadata API guide, "the metadata doesn't include the order of
active approval processes. Sometimes you have to reorder the approval
processes in the destination org after deployment" (api_meta.txt
L23066-23068). That reorder is a manual post-deploy step.
---
## Verification
Run these after the deploy, before trusting any Apex against the
process.
```sql
-- 1. The process the Apex names exists and is Active.
SELECT Id, DeveloperName, Name, State, TableEnumOrId, LockType, Type
FROM ProcessDefinition
WHERE DeveloperName = 'Expense_Approval'
```
Expect one row, `State = 'Active'`, `Type = 'Approval Process'`
(object_reference.txt L225398-225426). Zero rows means every
`setProcessDefinitionNameOrId('Expense_Approval')` in the codebase
fails.
```sql
-- 2. Nothing else on the object competes for a null process name.
SELECT DeveloperName, State, TableEnumOrId
FROM ProcessDefinition
WHERE TableEnumOrId = 'Expense__c' AND State = 'Active'
```
More than one row means a submission that leaves
`processDefinitionNameOrId` null is routed by org process order,
which the metadata does not carry.
```sql
-- 3. A test submission actually created an instance and a workitem.
SELECT Id, Status, SubmittedById, TargetObjectId,
(SELECT Id, ActorId FROM Workitems)
FROM ProcessInstance
WHERE ProcessDefinition.DeveloperName = 'Expense_Approval'
ORDER BY Id DESC
```
`Workitems` is the child relationship name for
`ProcessInstanceWorkitem` on `ProcessInstance`, and `Steps` is the
child relationship for `ProcessInstanceStep` (object_reference.txt
L226220-226240).
Setup check, for anything SOQL cannot see: **Setup → Process
Automation → Approval Processes**, pick the object, and confirm the
process order — the one thing the deployed metadata does not carry.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |