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 |
scripts/check_approval_process_apex_patterns.py
View on GitHub#!/usr/bin/env python3
"""Lint Apex that drives approval processes, against the processes actually deployed.
Stdlib only. Reads a DX metadata tree and reports findings as JSON on
stdout, in the same shape as the other checkers in this repo
(``{"score": int, "findings": [...], "summary": str}``).
Two halves, and the second is why ``--manifest-dir`` exists: the Apex
checks cross-reference the ``approvalProcesses/`` metadata in the same
tree, so a process name that appears only in a string literal is
detectable.
Metadata checks (``approvalProcesses/*.approvalProcess-meta.xml``)
-----------------------------------------------------------------
HIGH ``active`` missing or not ``true`` while Apex in the tree
names the process - submissions naming an inactive process
fail (Object Reference, ``ProcessDefinition.State``).
HIGH No ``approvalStep`` element at all.
MEDIUM No ``recordEditability`` - the deployed process falls back to
whatever the target org has rather than a declared value
(Metadata API Developer Guide, ``ApprovalProcess``).
MEDIUM ``allowRecall`` false while Apex in the tree calls
``setAction('Removed')`` - recall is administrator-only.
REVIEW ``allowedSubmitters`` narrower than ``owner`` /
``allInternalUsers`` while Apex calls ``setSubmitterId`` -
"the user must be one of the allowed submitters"
(Apex Reference Guide, ``setSubmitterId``).
Apex checks (``*.cls`` / ``*.trigger``)
---------------------------------------
CRITICAL A loop body that both constructs an
``Approval.Process*Request`` and calls ``Approval.process`` -
one DML statement per record against a 150-statement
transaction budget. The canonical chunking loop, which builds
the request list in an earlier loop and calls
``Approval.process(chunk, false)`` once per chunk, is not
flagged.
HIGH ``setProcessDefinitionNameOrId`` with a literal record Id
(``300...``) - not portable across orgs.
HIGH ``setAction`` with a wrong-case or past-tense value; only
``Approve``, ``Reject`` and ``Removed`` are valid.
HIGH A process developer name passed to
``setProcessDefinitionNameOrId`` that no approval process in
the manifest defines.
MEDIUM ``Approval.process(list)`` with no ``allOrNone`` argument -
defaults to true, so one bad row rolls the batch back.
MEDIUM ``Actor.IsActive`` / ``Actor.Username`` dereferenced without
``TYPEOF`` - ``ActorId`` is polymorphic over Group and User.
LOW ``ProcessInstanceWorkitem`` or ``ProcessInstanceStep``
filtered or ordered on ``CreatedDate``; the Object Reference
field tables document ``ElapsedTimeInDays`` instead.
Usage
-----
python3 check_approval_process_apex_patterns.py --manifest-dir force-app/main/default
python3 check_approval_process_apex_patterns.py path/to/classes path/to/approvalProcesses
"""
from __future__ import annotations
import argparse
import json
import re
import sys
import xml.etree.ElementTree as ET
from pathlib import Path
PROCESS_SUFFIX = ".approvalProcess-meta.xml"
APEX_SUFFIXES = (".cls", ".trigger")
SEVERITY_WEIGHTS = {"CRITICAL": 20, "HIGH": 10, "MEDIUM": 5, "LOW": 1, "REVIEW": 0}
SEVERITIES = tuple(SEVERITY_WEIGHTS)
WIDE_SUBMITTER_TYPES = {"owner", "creator", "allInternalUsers"}
VALID_ACTIONS = ("Approve", "Reject", "Removed")
# --- Apex patterns ---------------------------------------------------------
RE_PROCESS_NAME = re.compile(
r"setProcessDefinitionNameOrId\s*\(\s*['\"]([^'\"]+)['\"]\s*\)"
)
RE_HARDCODED_ID = re.compile(r"^300[a-zA-Z0-9]{12,15}$")
RE_SET_ACTION = re.compile(r"setAction\s*\(\s*['\"]([^'\"]*)['\"]\s*\)")
RE_SET_SUBMITTER = re.compile(r"setSubmitterId\s*\(")
RE_PROCESS_CALL = re.compile(r"Approval\s*\.\s*process\s*\(")
RE_NEW_REQUEST = re.compile(
r"new\s+Approval\s*\.\s*Process(Submit|Workitem)Request\s*\(", re.IGNORECASE
)
RE_ACTOR_FIELD = re.compile(r"\bActor\s*\.\s*(IsActive|Username|Name|Email)\b")
RE_TYPEOF = re.compile(r"\bTYPEOF\b", re.IGNORECASE)
RE_WORKITEM_SOQL = re.compile(
r"FROM\s+(ProcessInstanceWorkitem|ProcessInstanceStep)\b", re.IGNORECASE
)
RE_CREATEDDATE = re.compile(r"\bCreatedDate\b")
RE_LOOP_OPEN = re.compile(r"\b(for|while)\s*\(")
RE_BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.DOTALL)
RE_LINE_COMMENT = re.compile(r"//[^\n]*")
def local_name(tag: str) -> str:
return tag.split("}", 1)[-1]
def child(element: ET.Element | None, name: str) -> ET.Element | None:
"""First direct child named ``name``.
A leaf ``Element`` is falsy, so every caller must compare against
None. Never write ``el.find(a) or el.find(b)``.
"""
if element is None:
return None
for candidate in element:
if local_name(candidate.tag) == name:
return candidate
return None
def children(element: ET.Element | None, name: str) -> list[ET.Element]:
if element is None:
return []
return [c for c in element if local_name(c.tag) == name]
def text_of(element: ET.Element | None, name: str) -> str:
found = child(element, name)
if found is None or found.text is None:
return ""
return found.text.strip()
def strip_comments(text: str) -> str:
"""Blank out comments while preserving line numbering."""
def blank(match: re.Match[str]) -> str:
return re.sub(r"[^\n]", " ", match.group(0))
return RE_LINE_COMMENT.sub(blank, RE_BLOCK_COMMENT.sub(blank, text))
def line_no(text: str, pos: int) -> int:
return text.count("\n", 0, pos) + 1
def process_name_of(path: Path) -> str:
"""``Expense__c.Expense_Approval.approvalProcess-meta.xml`` -> Expense_Approval."""
stem = path.name[: -len(PROCESS_SUFFIX)]
return stem.split(".", 1)[1] if "." in stem else stem
# --- collection ------------------------------------------------------------
def iter_files(paths: list[Path], suffixes: tuple[str, ...]) -> list[Path]:
files: list[Path] = []
for path in paths:
if path.is_dir():
for suffix in suffixes:
files.extend(c for c in path.rglob(f"*{suffix}") if c.is_file())
elif path.is_file() and path.name.endswith(suffixes):
files.append(path)
return sorted(set(files))
def load_processes(files: list[Path]) -> tuple[dict[str, dict], list[str]]:
"""Parse each approval process into a small summary dict."""
processes: dict[str, dict] = {}
findings: list[str] = []
for path in files:
try:
root = ET.parse(path).getroot()
except ET.ParseError as exc:
findings.append(f"HIGH {path}: not well-formed XML ({exc})")
continue
submitter_types = {
text_of(node, "type")
for node in children(root, "allowedSubmitters")
if text_of(node, "type")
}
processes[process_name_of(path)] = {
"path": path,
"active": text_of(root, "active").lower() == "true",
"has_active_element": child(root, "active") is not None,
"allow_recall": text_of(root, "allowRecall").lower() == "true",
"has_allow_recall": child(root, "allowRecall") is not None,
"steps": len(children(root, "approvalStep")),
"record_editability": text_of(root, "recordEditability"),
"submitter_types": submitter_types,
}
return processes, findings
# --- Apex scanning ---------------------------------------------------------
def match_close(text: str, open_pos: int, opener: str, closer: str) -> int:
"""Index just past the ``closer`` matching the ``opener`` at ``open_pos``."""
depth = 0
for i in range(open_pos, len(text)):
if text[i] == opener:
depth += 1
elif text[i] == closer:
depth -= 1
if depth == 0:
return i + 1
return len(text)
def loop_body_spans(text: str) -> list[tuple[int, int]]:
"""``(start, end)`` offsets of every ``for`` / ``while`` body in ``text``.
Spans nest: an inner loop yields its own span as well as being
contained in the outer one. Callers therefore see the innermost
enclosing body for any offset, which is what the per-record DML check
wants.
"""
spans: list[tuple[int, int]] = []
for match in RE_LOOP_OPEN.finditer(text):
header_end = match_close(text, match.end() - 1, "(", ")")
cursor = header_end
while cursor < len(text) and text[cursor].isspace():
cursor += 1
if cursor >= len(text):
continue
if text[cursor] == "{":
spans.append((cursor, match_close(text, cursor, "{", "}")))
else:
# single-statement body, up to and including the semicolon
end = text.find(";", cursor)
spans.append((cursor, len(text) if end == -1 else end + 1))
return spans
def per_record_dml_loops(text: str) -> list[int]:
"""Offsets of ``Approval.process`` calls that run once per record.
A loop body that constructs a request *and* processes it does one DML
statement per iteration. A chunking loop - request list built earlier,
``Approval.process(chunk, false)`` called once per slice - does not
construct requests inside the processing loop and is not reported.
"""
offsets: list[int] = []
for start, end in loop_body_spans(text):
body = text[start:end]
if not RE_NEW_REQUEST.search(body):
continue
for call in RE_PROCESS_CALL.finditer(body):
offsets.append(start + call.start())
return sorted(set(offsets))
def balanced_call_args(text: str, open_paren: int) -> str:
"""Return the argument text of a call whose '(' is at ``open_paren``."""
depth = 0
for i in range(open_paren, len(text)):
if text[i] == "(":
depth += 1
elif text[i] == ")":
depth -= 1
if depth == 0:
return text[open_paren + 1 : i]
return ""
def scan_apex(path: Path, processes: dict[str, dict], resolve: bool) -> tuple[list[str], set[str], set[str]]:
findings: list[str] = []
named: set[str] = set()
actions: set[str] = set()
try:
raw = path.read_text(encoding="utf-8", errors="ignore")
except OSError as exc:
return [f"HIGH could not read {path}: {exc}"], named, actions
text = strip_comments(raw)
for match in RE_PROCESS_NAME.finditer(text):
name = match.group(1).strip()
named.add(name)
where = f"{path}:{line_no(text, match.start())}"
if RE_HARDCODED_ID.match(name):
findings.append(
f"HIGH {where}: setProcessDefinitionNameOrId uses the literal record Id "
f"`{name}`. Approval-process record Ids differ per org and per sandbox "
"refresh; pass the developer name instead (gotchas.md gotcha 1)"
)
elif resolve and name not in processes:
known = ", ".join(sorted(processes)) or "none"
findings.append(
f"HIGH {where}: setProcessDefinitionNameOrId('{name}') names a process "
f"that no approvalProcess metadata in this tree defines (found: {known}). "
"A submission naming a process that is absent or inactive fails "
"(gotchas.md gotcha 14)"
)
for match in RE_SET_ACTION.finditer(text):
value = match.group(1)
actions.add(value)
if value not in VALID_ACTIONS:
findings.append(
f"HIGH {path}:{line_no(text, match.start())}: setAction('{value}') is not "
"a valid action. The Apex Reference lists exactly Approve, Reject and "
"Removed, and only system administrators can specify Removed "
"(gotchas.md gotchas 4 and 5)"
)
for offset in per_record_dml_loops(text):
findings.append(
f"CRITICAL {path}:{line_no(text, offset)}: this loop body both constructs an "
"Approval request and calls Approval.process, so it issues one DML statement "
"per record against a 150-statement transaction budget. Build the request "
"list in one loop, then call Approval.process(chunk, false) per chunk "
"(gotchas.md gotcha 7)"
)
for match in RE_PROCESS_CALL.finditer(text):
where = f"{path}:{line_no(text, match.start())}"
open_paren = match.end() - 1
args = balanced_call_args(text, open_paren)
top_level_commas = 0
depth = 0
for ch in args:
if ch in "([{":
depth += 1
elif ch in ")]}":
depth -= 1
elif ch == "," and depth == 0:
top_level_commas += 1
if top_level_commas == 0 and args.strip():
findings.append(
f"MEDIUM {where}: Approval.process(...) called without an allOrNone "
"argument, which defaults to true - one failing row rolls the whole call "
"back. Pass false and read the per-row ProcessResults "
"(gotchas.md gotcha 2)"
)
if RE_WORKITEM_SOQL.search(text):
for match in RE_ACTOR_FIELD.finditer(text):
# TYPEOF anywhere in the file is treated as handled; the point
# is to catch code that has never heard of the polymorphism.
if not RE_TYPEOF.search(text):
findings.append(
f"MEDIUM {path}:{line_no(text, match.start())}: Actor.{match.group(1)} "
"dereferenced with no TYPEOF in the file. ActorId on "
"ProcessInstanceWorkitem and ProcessInstanceStep is polymorphic over "
"Group and User, so a queue-assigned request has no user at all "
"(gotchas.md gotcha 13)"
)
break
if RE_CREATEDDATE.search(text):
match = RE_CREATEDDATE.search(text)
assert match is not None
findings.append(
f"LOW {path}:{line_no(text, match.start())}: CreatedDate used alongside a "
"ProcessInstanceWorkitem / ProcessInstanceStep query. The Object Reference "
"field tables for these objects document ElapsedTimeInDays / InHours / "
"InMinutes as the filterable, sortable aging fields "
"(gotchas.md gotcha 13)"
)
return findings, named, actions
# --- metadata auditing -----------------------------------------------------
def audit_processes(
processes: dict[str, dict],
named_in_apex: set[str],
actions_in_apex: set[str],
submitter_set_in_apex: bool,
) -> list[str]:
findings: list[str] = []
for name, info in sorted(processes.items()):
path = info["path"]
referenced = name in named_in_apex
if not info["has_active_element"]:
findings.append(
f"HIGH {path}: no <active> element. It is a required field on "
"ApprovalProcess and the deploy will not set a value"
)
elif not info["active"] and referenced:
findings.append(
f"HIGH {path}: <active>false</active> while Apex in this tree submits to "
f"'{name}'. ProcessDefinition.State must be Active for the submission to "
"resolve (gotchas.md gotcha 14)"
)
if info["steps"] == 0:
findings.append(
f"HIGH {path}: no <approvalStep> defined, so nothing can be approved. "
"Each process supports up to 30 steps"
)
if not info["record_editability"]:
findings.append(
f"MEDIUM {path}: no <recordEditability>. Declare AdminOnly or "
"AdminOrCurrentApprover explicitly rather than inheriting whatever the "
"target org already has"
)
if "Removed" in actions_in_apex and info["has_allow_recall"] and not info["allow_recall"]:
findings.append(
f"MEDIUM {path}: <allowRecall>false</allowRecall> while Apex in this tree "
"calls setAction('Removed'). Recall is administrator-only in that "
"configuration (gotchas.md gotcha 5)"
)
if submitter_set_in_apex and not (info["submitter_types"] & WIDE_SUBMITTER_TYPES):
listed = ", ".join(sorted(info["submitter_types"])) or "none"
findings.append(
f"REVIEW {path}: Apex in this tree calls setSubmitterId, but "
f"allowedSubmitters is limited to [{listed}] with no owner / creator / "
"allInternalUsers entry. Any submitter outside that list fails its row "
"(gotchas.md gotcha 11)"
)
return findings
# --- output ----------------------------------------------------------------
def normalize_finding(finding: str) -> dict:
severity, _, message = finding.partition(" ")
if severity not in SEVERITIES:
severity, message = "REVIEW", finding
return {"severity": severity, "message": message.strip()}
def emit_result(findings: list[str], summary: str) -> int:
normalized = [normalize_finding(f) for f in findings]
score = max(0, 100 - sum(SEVERITY_WEIGHTS.get(i["severity"], 0) for i in normalized))
print(json.dumps({"score": score, "findings": normalized, "summary": summary}, indent=2))
if normalized:
print(f"WARN: {len(normalized)} finding(s) detected", file=sys.stderr)
return 1 if normalized else 0
def main() -> int:
parser = argparse.ArgumentParser(
description=(
"Lint approval-process Apex against the approval processes deployed "
"alongside it in a DX metadata tree."
)
)
parser.add_argument(
"paths",
nargs="*",
help="Files or directories to scan (alternative to --manifest-dir)",
)
parser.add_argument(
"--manifest-dir",
help="DX metadata root, e.g. force-app/main/default; scans approvalProcesses/ "
"and every .cls / .trigger under it, and resolves Apex process names against "
"the deployed metadata",
)
args = parser.parse_args()
root_dir: Path | None = None
targets: list[Path] = [Path(p) for p in args.paths]
if args.manifest_dir:
root_dir = Path(args.manifest_dir)
if not root_dir.exists():
return emit_result(
[f"HIGH --manifest-dir does not exist: {root_dir}"],
f"Could not read {root_dir}.",
)
targets.append(root_dir)
if not targets:
parser.error("provide one or more paths, or --manifest-dir")
process_files = iter_files(targets, (PROCESS_SUFFIX,))
apex_files = iter_files(targets, APEX_SUFFIXES)
if not process_files and not apex_files:
return emit_result(
["HIGH no approval-process metadata and no Apex files found"],
"Scanned 0 files; nothing matched the provided paths.",
)
processes, findings = load_processes(process_files)
resolve = bool(process_files)
named_in_apex: set[str] = set()
actions_in_apex: set[str] = set()
submitter_set = False
for path in apex_files:
apex_findings, named, actions = scan_apex(path, processes, resolve)
findings.extend(apex_findings)
named_in_apex |= named
actions_in_apex |= actions
try:
if RE_SET_SUBMITTER.search(strip_comments(path.read_text(encoding="utf-8", errors="ignore"))):
submitter_set = True
except OSError:
pass
findings.extend(audit_processes(processes, named_in_apex, actions_in_apex, submitter_set))
notes: list[str] = []
if not resolve:
notes.append(
"no approvalProcess metadata in scope, so Apex process names were not resolved"
)
if not apex_files:
notes.append("no Apex files in scope, so only the metadata was audited")
suffix = f" Note: {'; '.join(notes)}." if notes else ""
summary = (
f"Scanned {len(process_files)} approval-process file(s) and {len(apex_files)} "
f"Apex file(s); {len(findings)} finding(s) detected.{suffix}"
)
return emit_result(findings, summary)
if __name__ == "__main__":
sys.exit(main())
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 |