Skip to content

Commit dcc73db

Browse files
svaroteauxSFDCsvaroteauxSFDC
committed
feat: add building-flow-approval-process skill
Adds a new skill for Salesforce Flow Approval Processes (processType: ApprovalWorkflow), a distinct flow type not covered by the existing generating-flow skill. Key contributions: - Full architecture guide: orchestration, Background Steps, Approval Steps, Screen Flows, WebLink trigger, Lightning page components - Explicit delegation rule: AutoLaunched and Screen Flows are generated via the generating-flow MCP pipeline; only the ApprovalWorkflow orchestration XML is written manually - Hard-stop constraints mapped to known deployment/runtime errors - XML reference patterns in references/xml-patterns.md - Common errors quick reference table with root causes and fixes - Required deployment order to avoid dependency failures
1 parent 672707e commit dcc73db

2 files changed

Lines changed: 414 additions & 0 deletions

File tree

‎skills/building-flow-approval-process/SKILL.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
name: building-flow-approval-process
3+
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)."
4+
metadata:
5+
version: "1.0"
6+
---
7+
8+
## Goal
9+
10+
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.
11+
12+
## When to Use This Skill
13+
14+
Activate this skill for:
15+
- Creating a new multi-level approval process using Flows (not Classic Approval Processes)
16+
- Configuring `orchestratedStages`, Background Steps, and Approval Steps in an `ApprovalWorkflow` flow
17+
- Setting up the WebLink button that launches the orchestration
18+
- Debugging errors specific to Flow Approval Processes (`Submit for Approval not supported`, output reference syntax failures, subflow restrictions)
19+
- Adding `Flow Orchestration Work Guide` and `Approval Trace` components to a record page
20+
21+
**Delegate elsewhere** for Classic Approval Processes (Setup > Approval Processes), record-triggered flows, or Apex-based approval routing.
22+
23+
## Classic vs. Flow Approval Process — Critical Distinction
24+
25+
| | Classic Approval Process | Flow Approval Process |
26+
|---|---|---|
27+
| Setup location | Setup > Approval Processes | Setup > Flows (`processType: ApprovalWorkflow`) |
28+
| Trigger | `Submit for Approval` action | WebLink URL button → `/flow/FlowApiName?params` |
29+
| Entry conditions | Record criteria | Background Step + Evaluation Flow |
30+
| Steps | Linear steps | `orchestratedStages` containing `stageSteps` |
31+
32+
**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."*
33+
34+
## Flow Generation — Mandatory Delegation
35+
36+
An ApprovalWorkflow solution involves multiple flows. Apply this rule for each:
37+
38+
| Flow type | How to generate |
39+
|---|---|
40+
| AutoLaunched flows (calculation, evaluation, status update) | **Use `generating-flow` skill** — 3-step MCP pipeline (`fetchGroundedObjectMetadata` → `flowElementSelection` → `flowElementGeneration`). Never write XML manually. |
41+
| Screen Flow (approver review UI) | **Use `generating-flow` skill** — same 3-step MCP pipeline. |
42+
| ApprovalWorkflow orchestration (`processType: ApprovalWorkflow`) | **Write XML manually** — the MCP pipeline does not support this processType. Use the XML patterns in `references/xml-patterns.md`. |
43+
44+
Generate all component flows **before** the orchestration. The orchestration references them by API name in `actionName` attributes.
45+
46+
## Core Workflow
47+
48+
1. **Define entry variables** — declare the 4 mandatory input variables on the orchestration
49+
2. **Generate supporting flows** — use the `generating-flow` skill to create each AutoLaunched flow and the Screen Flow via the MCP pipeline
50+
3. **Design orchestration stages** — model each approval level as an `orchestratedStage` with Background Steps and Approval Steps
51+
4. **Wire decision routing** — use Decision elements between stages, referencing Background Step outputs via `{!StepName.Outputs.variableName}` syntax
52+
5. **Write the ApprovalWorkflow orchestration XML** — using patterns from `references/xml-patterns.md`
53+
6. **Create the WebLink trigger** — build the URL button on the object; add to the page layout
54+
7. **Add Lightning components** — place Flow Orchestration Work Guide and Approval Trace on the record page
55+
8. **Deploy in order** — follow the required deployment sequence to avoid dependency failures
56+
9. **Validate** — submit a test record and verify each stage transitions correctly
57+
58+
## Architecture Pattern
59+
60+
```
61+
WebLink Button
62+
└── /flow/ApprovalOrchestration?recordId=...&submitter={!$User.Id}&retURL=...
63+
└── ApprovalWorkflow (processType: ApprovalWorkflow)
64+
├── Background Step → AutoLaunched Flow (calculate level / init status)
65+
├── Decision (route by level output)
66+
├── Stage N1
67+
│ ├── Approval Step (Screen Flow — approver UI)
68+
│ └── Background Step (update status)
69+
├── Decision (Approve / Reject)
70+
├── Stage N2 — same pattern
71+
└── Stage N3 — same pattern
72+
```
73+
74+
## Required Orchestration Variables
75+
76+
Declare these 4 input variables on every ApprovalWorkflow orchestration:
77+
78+
| Variable | dataType | isInput |
79+
|---|---|---|
80+
| `recordId` | String | true |
81+
| `submitter` | String | true |
82+
| `submissionComments` | String | true |
83+
| `firstApprover` | String | true |
84+
85+
Missing any of these causes runtime errors even if the variable is not used in the flow logic.
86+
87+
## Step Types Reference
88+
89+
### Background Step
90+
- `actionType: stepBackground` / `stepSubtype: BackgroundStep`
91+
- Calls an AutoLaunched flow (`TriggerType: None`)
92+
- `requiresAsyncProcessing: false`, `runAsUser: false`, `shouldLock: false`
93+
- Inputs accept variable references or string literals only — no calculated expressions
94+
95+
### Approval Step
96+
- `actionType: stepApproval` / `stepSubtype: ApprovalStep`
97+
- Calls a Screen Flow for the approver UI
98+
- `requiresAsyncProcessing: true`, `runAsUser: true`, `shouldLock: true`
99+
- `assigneeType`: `Queue`, `User`, or `Group`
100+
- Output `approvalDecision` must be exactly `"Approve"` or `"Reject"` (case-sensitive)
101+
102+
## Output Reference Syntax
103+
104+
Reference Background Step outputs in downstream elements:
105+
106+
```
107+
{!StepName.Outputs.variableName}
108+
```
109+
110+
- In a Decision element: `<leftValueReference>CalcLevel.Outputs.approvalLevel</leftValueReference>`
111+
- In a subsequent Background Step input: `<elementReference>CalcLevel.Outputs.approvalLevel</elementReference>`
112+
- Approval decision: `<leftValueReference>Approbation_N1.Outputs.approvalDecision</leftValueReference>`
113+
114+
## Screen Flow — Required Variables
115+
116+
The approver Screen Flow must declare these variables with exact names:
117+
118+
**Inputs:** `approvalInformation` (String), `recordId` (String)
119+
120+
**Outputs:** `approvalDecision` (String) — value must be exactly `"Approve"` or `"Reject"`; `approvalComments` (String)
121+
122+
Add a `faultConnector` on every `recordLookups` element displaying `{!$Flow.FaultMessage}`.
123+
124+
## Hard-Stop Constraints
125+
126+
These cause deployment or runtime failures:
127+
128+
- **No `<subflows>` element** in an ApprovalWorkflow — use Background Steps instead
129+
- **No Custom Error elements** in AutoLaunched flows called by Background Steps (`TriggerType: None`)
130+
- **No calculated expressions** as Background Step inputs — variable references and string literals only
131+
- **No `Submit for Approval` action** to trigger an ApprovalWorkflow — WebLink URL only
132+
- **No** `hasMenubar`, `height`, `position`, `isResizable` on a WebLink with `openType: replace`
133+
- **Deletion via Metadata API fails** when the flow has execution history — delete from Setup UI
134+
135+
## Required Lightning Page Components
136+
137+
Add both components to the record page via Lightning App Builder:
138+
139+
1. **Flow Orchestration Work Guide** — shows pending work items to approvers
140+
2. **Approval Trace** — shows approval history
141+
142+
Without these, approvers have no interface to process their work items.
143+
144+
## Deployment Order
145+
146+
Deploy in this sequence to avoid dependency errors:
147+
148+
1. Custom objects and fields
149+
2. AutoLaunched flows (calculation, evaluation, status update)
150+
3. Screen Flow (approver review UI)
151+
4. ApprovalWorkflow orchestration
152+
5. WebLink + page layout
153+
154+
```bash
155+
SF_LOG_FILE=/dev/null sf project deploy start -m "Flow:MyFlowName" --ignore-conflicts -o my-org
156+
```
157+
158+
## Common Errors Quick Reference
159+
160+
| Error | Cause | Fix |
161+
|---|---|---|
162+
| `This action doesn't submit a record for approval using Flow Approval Processes` | Classic "Submit for Approval" action used | Replace with WebLink URL button |
163+
| `CalcLevel.approvalLevel doesn't exist` | Missing `Outputs.` in reference syntax | Use `CalcLevel.Outputs.approvalLevel` |
164+
| `firstApprover / submissionComments received nothing` | Required orchestration variables missing | Declare all 4 mandatory input variables |
165+
| `Flows of type ApprovalWorkflow can't include Subflow elements` | Subflow element used | Replace with Background Step |
166+
| `Can't include Custom Error elements when TriggerType is None` | Custom Error in AutoLaunched flow | Remove Custom Error; let fault propagate |
167+
| `insufficient access rights on cross-reference id` on delete | Flow has execution history | Delete from Setup UI, not Metadata API |
168+
| WebLink deployment failure with `openType: replace` | Forbidden properties included | Remove `hasMenubar`, `hasScrollbars`, `height`, `position`, `isResizable` |
169+
170+
## Additional Resources
171+
172+
### Reference Files
173+
174+
For complete XML patterns and templates, consult:
175+
- **`references/xml-patterns.md`** — Full XML for orchestration variables, WebLink, Background Step, Approval Step, and Screen Flow variables

0 commit comments

Comments
 (0)