forcedotcom · svaroteauxSFDC · Jun 12, 2026
diff --git a/skills/building-flow-approval-process/SKILL.md b/skills/building-flow-approval-process/SKILL.md
@@ -0,0 +1,175 @@
+---
+name: building-flow-approval-process
+description: "Build Salesforce Flow Approval Processes (processType: ApprovalWorkflow). Use when the user wants to 'create a flow approval process', 'build an ApprovalWorkflow', 'set up multi-level approval with flows', 'configure approval orchestration', 'add approval stages to a flow', or encounters errors such as 'Submit for Approval doesn\\'t work with Flow Approval Processes' or 'Outputs reference doesn\\'t exist'. Not for Classic Approval Processes (Setup > Approval Processes)."
+metadata:
+  version: "1.0"
+---
+
+## Goal
+
+Design, implement, and deploy Salesforce Flow Approval Processes (`processType: ApprovalWorkflow`), covering the full stack: orchestration flow, background steps, approval steps, screen flows, WebLink triggers, and required Lightning page components.
+
+## When to Use This Skill
+
+Activate this skill for:
+- Creating a new multi-level approval process using Flows (not Classic Approval Processes)
+- Configuring `orchestratedStages`, Background Steps, and Approval Steps in an `ApprovalWorkflow` flow
+- Setting up the WebLink button that launches the orchestration
+- Debugging errors specific to Flow Approval Processes (`Submit for Approval not supported`, output reference syntax failures, subflow restrictions)
+- Adding `Flow Orchestration Work Guide` and `Approval Trace` components to a record page
+
+**Delegate elsewhere** for Classic Approval Processes (Setup > Approval Processes), record-triggered flows, or Apex-based approval routing.
+
+## Classic vs. Flow Approval Process — Critical Distinction
+
+| | Classic Approval Process | Flow Approval Process |
+|---|---|---|
+| Setup location | Setup > Approval Processes | Setup > Flows (`processType: ApprovalWorkflow`) |
+| Trigger | `Submit for Approval` action | WebLink URL button → `/flow/FlowApiName?params` |
+| Entry conditions | Record criteria | Background Step + Evaluation Flow |
+| Steps | Linear steps | `orchestratedStages` containing `stageSteps` |
+
+**Never use the "Submit for Approval" Flow action with an ApprovalWorkflow.** Salesforce documentation states explicitly: *"This action doesn't submit a record for approval using Flow Approval Processes."*
+
+## Flow Generation — Mandatory Delegation
+
+An ApprovalWorkflow solution involves multiple flows. Apply this rule for each:
+
+| Flow type | How to generate |
+|---|---|
+| AutoLaunched flows (calculation, evaluation, status update) | **Use `generating-flow` skill** — 3-step MCP pipeline (`fetchGroundedObjectMetadata` → `flowElementSelection` → `flowElementGeneration`). Never write XML manually. |
+| Screen Flow (approver review UI) | **Use `generating-flow` skill** — same 3-step MCP pipeline. |
+| ApprovalWorkflow orchestration (`processType: ApprovalWorkflow`) | **Write XML manually** — the MCP pipeline does not support this processType. Use the XML patterns in `references/xml-patterns.md`. |
+
+Generate all component flows **before** the orchestration. The orchestration references them by API name in `actionName` attributes.
+
+## Core Workflow
+
+1. **Define entry variables** — declare the 4 mandatory input variables on the orchestration
+2. **Generate supporting flows** — use the `generating-flow` skill to create each AutoLaunched flow and the Screen Flow via the MCP pipeline
+3. **Design orchestration stages** — model each approval level as an `orchestratedStage` with Background Steps and Approval Steps
+4. **Wire decision routing** — use Decision elements between stages, referencing Background Step outputs via `{!StepName.Outputs.variableName}` syntax
+5. **Write the ApprovalWorkflow orchestration XML** — using patterns from `references/xml-patterns.md`
+6. **Create the WebLink trigger** — build the URL button on the object; add to the page layout
+7. **Add Lightning components** — place Flow Orchestration Work Guide and Approval Trace on the record page
+8. **Deploy in order** — follow the required deployment sequence to avoid dependency failures
+9. **Validate** — submit a test record and verify each stage transitions correctly
+
+## Architecture Pattern
+
+```
+WebLink Button
+  └── /flow/ApprovalOrchestration?recordId=...&submitter={!$User.Id}&retURL=...
+        └── ApprovalWorkflow (processType: ApprovalWorkflow)
+              ├── Background Step → AutoLaunched Flow (calculate level / init status)
+              ├── Decision (route by level output)
+              ├── Stage N1
+              │     ├── Approval Step (Screen Flow — approver UI)
+              │     └── Background Step (update status)
+              ├── Decision (Approve / Reject)
+              ├── Stage N2 — same pattern
+              └── Stage N3 — same pattern
+```
+
+## Required Orchestration Variables
+
+Declare these 4 input variables on every ApprovalWorkflow orchestration:
+
+| Variable | dataType | isInput |
+|---|---|---|
+| `recordId` | String | true |
+| `submitter` | String | true |
+| `submissionComments` | String | true |
+| `firstApprover` | String | true |
+
+Missing any of these causes runtime errors even if the variable is not used in the flow logic.
+
+## Step Types Reference
+
+### Background Step
+- `actionType: stepBackground` / `stepSubtype: BackgroundStep`
+- Calls an AutoLaunched flow (`TriggerType: None`)
+- `requiresAsyncProcessing: false`, `runAsUser: false`, `shouldLock: false`
+- Inputs accept variable references or string literals only — no calculated expressions
+
+### Approval Step
+- `actionType: stepApproval` / `stepSubtype: ApprovalStep`
+- Calls a Screen Flow for the approver UI
+- `requiresAsyncProcessing: true`, `runAsUser: true`, `shouldLock: true`
+- `assigneeType`: `Queue`, `User`, or `Group`
+- Output `approvalDecision` must be exactly `"Approve"` or `"Reject"` (case-sensitive)
+
+## Output Reference Syntax
+
+Reference Background Step outputs in downstream elements:
+
+```
+{!StepName.Outputs.variableName}
+```
+
+- In a Decision element: `<leftValueReference>CalcLevel.Outputs.approvalLevel</leftValueReference>`
+- In a subsequent Background Step input: `<elementReference>CalcLevel.Outputs.approvalLevel</elementReference>`
+- Approval decision: `<leftValueReference>Approbation_N1.Outputs.approvalDecision</leftValueReference>`
+
+## Screen Flow — Required Variables
+
+The approver Screen Flow must declare these variables with exact names:
+
+**Inputs:** `approvalInformation` (String), `recordId` (String)
+
+**Outputs:** `approvalDecision` (String) — value must be exactly `"Approve"` or `"Reject"`; `approvalComments` (String)
+
+Add a `faultConnector` on every `recordLookups` element displaying `{!$Flow.FaultMessage}`.
+
+## Hard-Stop Constraints
+
+These cause deployment or runtime failures:
+
+- **No `<subflows>` element** in an ApprovalWorkflow — use Background Steps instead
+- **No Custom Error elements** in AutoLaunched flows called by Background Steps (`TriggerType: None`)
+- **No calculated expressions** as Background Step inputs — variable references and string literals only
+- **No `Submit for Approval` action** to trigger an ApprovalWorkflow — WebLink URL only
+- **No** `hasMenubar`, `height`, `position`, `isResizable` on a WebLink with `openType: replace`
+- **Deletion via Metadata API fails** when the flow has execution history — delete from Setup UI
+
+## Required Lightning Page Components
+
+Add both components to the record page via Lightning App Builder:
+
+1. **Flow Orchestration Work Guide** — shows pending work items to approvers
+2. **Approval Trace** — shows approval history
+
+Without these, approvers have no interface to process their work items.
+
+## Deployment Order
+
+Deploy in this sequence to avoid dependency errors:
+
+1. Custom objects and fields
+2. AutoLaunched flows (calculation, evaluation, status update)
+3. Screen Flow (approver review UI)
+4. ApprovalWorkflow orchestration
+5. WebLink + page layout
+
+```bash
+SF_LOG_FILE=/dev/null sf project deploy start -m "Flow:MyFlowName" --ignore-conflicts -o my-org
+```
+
+## Common Errors Quick Reference
+
+| Error | Cause | Fix |
+|---|---|---|
+| `This action doesn't submit a record for approval using Flow Approval Processes` | Classic "Submit for Approval" action used | Replace with WebLink URL button |
+| `CalcLevel.approvalLevel doesn't exist` | Missing `Outputs.` in reference syntax | Use `CalcLevel.Outputs.approvalLevel` |
+| `firstApprover / submissionComments received nothing` | Required orchestration variables missing | Declare all 4 mandatory input variables |
+| `Flows of type ApprovalWorkflow can't include Subflow elements` | Subflow element used | Replace with Background Step |
+| `Can't include Custom Error elements when TriggerType is None` | Custom Error in AutoLaunched flow | Remove Custom Error; let fault propagate |
+| `insufficient access rights on cross-reference id` on delete | Flow has execution history | Delete from Setup UI, not Metadata API |
+| WebLink deployment failure with `openType: replace` | Forbidden properties included | Remove `hasMenubar`, `hasScrollbars`, `height`, `position`, `isResizable` |
+
+## Additional Resources
+
+### Reference Files
+
+For complete XML patterns and templates, consult:
+- **`references/xml-patterns.md`** — Full XML for orchestration variables, WebLink, Background Step, Approval Step, and Screen Flow variables