forcedotcom/sf-skills / plugins/builder/service-omni/skills/service-omni-routing-flow-deploy
service-omni-routing-flow-deploy
VerifiedUse to deploy an Omni-Channel routing Flow for Case or VoiceCall and verify it routes work items to a queue or by skill. Supports the Case and VoiceCall steel thread with an autolaunched dryRun-gated variant and record-triggered QueueBased and SkillsBased variants. --trigger deploys a record-triggered variant; --routing-type SkillsBased evaluates WorkSkillRouting rules with a non-null skillOption; --runtime-proof checks routing evidence and, for SkillsBased, SkillRequirement rows. Triggers: deploy Omni routing flow for Case, deploy Omni routing flow for VoiceCall, wire VoiceCall routing, create a record-triggered Omni routing flow, verify a Case routing flow, deploy skills-based routing flow. Do not use for screen flows, platform-event-triggered flows, or Flow Tests.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.6 KB |
| assets/force-app/main/default/flows/Omni_Route_Case_Trigger.SkillsBased.flow-meta.xml | config | 4.1 KB |
| assets/force-app/main/default/flows/Omni_Route_Case_Trigger.flow-meta.xml | config | 3.5 KB |
| assets/force-app/main/default/flows/Omni_Route_Cases.flow-meta.xml | config | 4.9 KB |
| assets/force-app/main/default/flows/Omni_Route_VoiceCall_Trigger.SkillsBased.flow-meta.xml | config | 4.1 KB |
| assets/force-app/main/default/flows/Omni_Route_VoiceCall_Trigger.flow-meta.xml | config | 3.6 KB |
| assets/force-app/main/default/flows/Omni_Route_VoiceCalls.flow-meta.xml | config | 4.9 KB |
| assets/package.xml | config | 387 B |
| assets/sfdx-project.json | config | 194 B |
| references/api-notes.md | markdown | 16.3 KB |
| scripts/deploy-and-report.shexecutable | script | 35.4 KB |
references/api-notes.md
View on GitHub# API notes — Flow (v66) + Actions REST invocation
## Two flow variants shipped by this skill
This skill ships **two** Flow assets under `assets/force-app/main/default/flows/`. They solve two different problems and are verified two different ways — do not conflate them.
| Asset | processType | Verified by | Routes real work? | Purpose |
|---|---|---|---|---|
| `Omni_Route_Cases` | `AutoLaunchedFlow` | Actions REST `dryRun` invoke | **No** (dry-run gate) | Proves headless CLI invocability — "can the platform/CLI execute a routing flow without a real work item?" |
| `Omni_Route_Case_Trigger` | `AutoLaunchedFlow` + record trigger (`RecordAfterSave`, Case Create) | Record DML → PendingServiceRouting / AgentWork query | **Yes** | Production routing — fires on real Case insert, calls `routeWork`, hands the Case to Omni-Channel for distribution |
The autolaunched variant answers *"is flow invocation wired up?"* in one HTTP call with no side effects. The record-triggered variant answers *"do real Cases actually reach an agent?"* — which can only be proven by inserting a Case and observing the routing side effects. Both are legitimate parts of the AFCC contract: the smoke test de-risks the CLI/headless path; the trigger closes the "basic happy-path omni flow which routes work item to given queue" gap.
**Why the trigger flow is `AutoLaunchedFlow` with a `<start>` record trigger, not a separate processType:** Salesforce implements record-triggered flows as `AutoLaunchedFlow` process type plus a `<start>` block carrying `<object>`, `<recordTriggerType>`, and `<triggerType>RecordAfterSave</triggerType>`. There is no distinct `RecordAfterSave` processType value — the trigger semantics live entirely in `<start>`. This is why the processType matrix below lists record-triggered rows: same processType, different `<start>` shape.
### Verifying the record-triggered variant (no Actions REST — use record DML)
The trigger flow is **not** invocable via Actions REST (record-triggered flows aren't exposed as custom actions). Verify it by exercising the trigger and observing side effects:
```bash
# 1. baseline
PSR0=$(sf data query -o "$ORG" -q "SELECT COUNT(Id) c FROM PendingServiceRouting" --json | jq -r '.result.records[0].c')
AW0=$(sf data query -o "$ORG" -q "SELECT COUNT(Id) c FROM AgentWork" --json | jq -r '.result.records[0].c')
# 2. insert a Case (fires the trigger)
CASE=$(sf data create record -o "$ORG" --sobject Case \
--values "Subject='Omni trigger verify' Status='New' Origin='Email'" --json | jq -r '.result.id')
# 3. re-query — PSR should be +1 for this Case; AgentWork +1 if an agent is online
sf data query -o "$ORG" -q "SELECT WorkItemId, IsReadyForRouting, RoutingType, QueueId FROM PendingServiceRouting WHERE WorkItemId='$CASE'" --json | jq -c '.result.records[]'
# 4. cleanup
sf data delete record -o "$ORG" --sobject Case --record-id "$CASE"
```
Success signals: `PendingServiceRouting 0 → 1` with `IsReadyForRouting=true, RoutingType=QueueBased`, and `AgentWork +1` in `Assigned` status against the target queue when an agent is online with a Case-capable presence status. `AgentWork` does not increment when no agent is online — the PSR row alone (`IsReadyForRouting=true`) is sufficient proof the flow routed correctly; agent assignment is a separate Omni-distribution concern.
### Token resolution (record-triggered variant portability)
`Omni_Route_Case_Trigger` carries **tokenized** org-specific IDs so the asset is portable across the 15K-org migration fleet — hardcoding IDs would break every org but the one it was authored against. Tokens and how to resolve them by DeveloperName at deploy time:
| Token | Resolve from | Query |
|---|---|---|
| `__SERVICE_CHANNEL_ID__` | ServiceChannel (Case) | `SELECT Id FROM ServiceChannel WHERE RelatedEntity='Case'` |
| `__SERVICE_CHANNEL_DEVNAME__` | ServiceChannel | `SELECT DeveloperName FROM ServiceChannel WHERE RelatedEntity='Case'` |
| `__SERVICE_CHANNEL_LABEL__` | ServiceChannel | `SELECT MasterLabel FROM ServiceChannel WHERE RelatedEntity='Case'` |
| `__QUEUE_ID__` | Group (Queue) | `SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='<QueueDN>'` |
| `__ROUTING_CONFIG_ID__` | QueueRoutingConfig | `SELECT Id FROM QueueRoutingConfig WHERE DeveloperName='<ConfigDN>'` |
Resolve each token against the target org, `sd`/`sed`-substitute into a materialized copy of the asset, then deploy the resolved copy. Never commit the resolved copy — the committed asset stays tokenized.
## Flow XML skeleton (autolaunched)
Minimum shape a Flow XML must have to be deployable AND invocable via Actions REST:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
<apiVersion>66.0</apiVersion>
<label>Omni Route Cases</label>
<processType>AutoLaunchedFlow</processType>
<status>Active</status>
<start>
<locationX>50</locationX>
<locationY>0</locationY>
<connector>
<targetReference>Some_Element</targetReference>
</connector>
</start>
<variables>
<name>dryRun</name>
<dataType>Boolean</dataType>
<isInput>true</isInput>
<isOutput>false</isOutput>
</variables>
<variables>
<name>dryRunOk</name>
<dataType>Boolean</dataType>
<isInput>false</isInput>
<isOutput>true</isOutput>
</variables>
...
</Flow>
```
**Required for CLI invocation:**
| Element | Required | Notes |
|---|---|---|
| `<processType>AutoLaunchedFlow</processType>` | yes | Screen/record-triggered/event-triggered flows are NOT exposed as custom actions |
| `<status>Active</status>` | yes | Draft/Obsolete flows deploy but return 404 from Actions REST |
| `<label>` | yes | Display label; ≤ 80 chars |
| At least one `<start>` connector + one downstream element | yes | Empty flows fail schema validation |
| Boolean input `dryRun` + Boolean output `dryRunOk` | for this skill's smoke test | The invocation posts `{"inputs":[{"dryRun":true}]}` and expects `outputValues.dryRunOk=true` |
**processType matrix** — which flow types support which invocation paths:
| processType | Deploy via Metadata API | Invoke via Actions REST | Invoke via `sf apex run` (`Flow.Interview.<Name>`) | Invoke via record DML |
|---|---|---|---|---|
| `AutoLaunchedFlow` | yes | **yes** | yes | no |
| `Flow` (screen flow) | yes | no | no | no (needs Lightning/Experience runtime) |
| `AutoLaunchedFlowFromAnywhere` | yes | yes | yes | no |
| `RecordAfterSave` / `RecordBeforeSave` (record-triggered — `Omni_Route_Case_Trigger`) | yes | no | no | **yes** (trigger via `sf data create record` / `sf data update record`) |
| `RoutingFlow` (Omni routing type) | yes | limited | limited | no (platform invokes when work item enters queue) |
| `CustomEvent` (platform-event-triggered) | yes | no | no | **yes** (publish via `sf data create record --sobject <Event__e>`) |
For Omni routing specifically, the recommended shape is `AutoLaunchedFlow` (this skill's asset) — it can be invoked both by the platform (when registered on a Queue's Routing Configuration) AND by the CLI for smoke testing. `RoutingFlow` processType is more restrictive.
**`RoutingFlow` rejects `<runInMode>`:** if you author a flow of type `RoutingFlow` (rather than the `AutoLaunchedFlow` this skill ships), a `<runInMode>SystemModeWithoutSharing</runInMode>` element fails the deploy with "Because the flow is of type RoutingFlow, it can't be configured to always run in system context." Drop `<runInMode>` entirely from `RoutingFlow`-type flows.
## `routeWork` routing targets
The `routeWork` action accepts several mutually exclusive target types; set exactly one pair and let `routingType` select which applies:
| Target inputs | Routes to |
|---|---|
| `queueId` / `queueLabel` | a queue (most common) |
| `agentId` / `agentLabel` | a specific agent |
| `botId` / `botLabel` | an Einstein / Service Agent bot |
| `copilotId` / `copilotLabel` | a Copilot |
| `agentforceEmployeeAgentId` / `agentforceEmployeeAgentLabel` | an Agentforce Employee Agent (the escalation handoff target) |
| `digitalWorkerId` / `digitalWorkerLabel` | an Agentforce Orchestrator |
| `externalConversationBotId` / `externalConversationBotLabel` | an external conversation bot |
## Actions REST API endpoint
```http
POST /services/data/v<API>/actions/custom/flow/<FlowDeveloperName>
Content-Type: application/json
Authorization: Bearer <access_token>
{
"inputs": [
{ "dryRun": true }
]
}
```
**Success response** (HTTP 200):
```json
[
{
"actionName": "Omni_Route_Cases",
"errors": null,
"isSuccess": true,
"outputValues": {
"dryRunOk": true,
"routed": false
}
}
]
```
Note: response is always a JSON **array**, even for a single-input call. `outputValues` contains every Flow variable marked `isOutput=true`.
**Failure responses:**
| HTTP | Body | Meaning | Fix |
|---|---|---|---|
| 200 | `[{"isSuccess": false, "errors": [{"message": "..."}]}]` | Flow ran but failed a decision/action | Read `.errors[0].message`; usually a variable-type mismatch or a missing prereq for the non-dry-run branch |
| 404 | `[{"errorCode":"NOT_FOUND","message":"The requested resource does not exist"}]` | Flow DeveloperName not found OR flow is Draft/Obsolete | Confirm the Flow exists and `<status>Active</status>` |
| 400 | `[{"errorCode":"INVALID_TYPE","message":"..."}]` | `<processType>` is not AutoLaunched (typically `Flow` for screen flows) | Rewrite the flow as autolaunched, or skip invocation for this flow type |
| 401 | `INVALID_SESSION_ID` | Session expired | Re-authenticate: `sf org login web --alias <alias>` |
| 403 | `INSUFFICIENT_ACCESS` | User running the CLI lacks "Run Flows" permission | Grant Run Flows permission, or run as admin |
## SF CLI invocation patterns
### Path 1 — `sf api request rest` (preferred; language-agnostic, structured JSON)
```bash
sf api request rest \
--method POST \
--target-org <alias> \
--body '{"inputs":[{"dryRun":true}]}' \
/services/data/v66.0/actions/custom/flow/Omni_Route_Cases
```
Body must be valid JSON. The path is passed as a positional arg (no `--url` flag on recent `sf` versions — the last positional is the path).
**Parsing pitfall — beta warning on stdout:** as of `sf` CLI v2.139+, `sf api request rest` prints a `Warning: This command is currently in beta. ...` line to **stdout** (not stderr) before the JSON body. Naive `jq` parsing chokes on it. Strip everything up to the first `[` or `{`:
```bash
raw=$(sf api request rest --method POST --target-org "$ORG" --body "$BODY" "$PATH_")
json=$(printf '%s' "$raw" | awk '/^[[{]/,0')
echo "$json" | jq -r '.[0].outputValues.dryRunOk'
```
This skill's deploy-and-report.sh does exactly this. If Salesforce ever removes the beta warning, the `awk` filter is a no-op — safe forward.
### Path 2 — `sf apex run` (when Apex context is needed)
```bash
cat > /tmp/invoke.apex <<'EOF'
Map<String, Object> params = new Map<String, Object>{ 'dryRun' => true };
Flow.Interview.Omni_Route_Cases flow = new Flow.Interview.Omni_Route_Cases(params);
flow.start();
System.debug('OUT: dryRunOk=' + flow.getVariableValue('dryRunOk'));
EOF
sf apex run -f /tmp/invoke.apex -o <alias>
```
Returns unstructured `System.debug` output; parse with a regex if scripting. Requires no additional metadata beyond the Flow itself.
### Path 3 — `sf flow test run` (only if FlowTest metadata is shipped)
```bash
sf flow test run --flow-api-name Omni_Route_Cases --target-org <alias>
```
Requires a `FlowTest:<TestName>` metadata component that carries assertions. Heavier deploy surface; not used by this skill's smoke test.
## Deploy semantics
Metadata API deploy of `Flow:<DN>` returns per-file state:
- `Created` — new Flow record (first deploy or new DeveloperName)
- `Changed` — Flow existed, deploy created a new version
- `Unchanged` — Flow existed AND deploy determined no new version was needed
**Flow-specific quirk: `Changed` on identical redeploy is normal.** Unlike `ServicePresenceStatus`, `Queue`, `ServiceChannel`, and other static metadata types, Flows are not byte-idempotent through the Metadata API. Flow versioning treats every deploy as a potential new version — even when the deployed XML is byte-identical to the currently-Active version, the response is typically `Changed` and a new inactive version number is bumped internally. A first deploy returns `Created`; a second identical deploy returns `Changed` with a new deploy Id.
**Implication for the coordinator:** treat `Changed` for Flow components as "successfully redeployed" rather than "operator modified the flow." The skill's `status: "updated"` on second run does not necessarily mean anything semantically changed. If the coordinator needs true operator-modification detection, compare the `<label>`, `<processType>`, `<status>`, and top-level `<variables>` block between deploys.
**Workaround for strict idempotency:** deploy with `<status>Draft</status>` and only activate on first deploy — subsequent deploys of identical Draft XML often return `Unchanged`. But this breaks the CLI-invocability contract (Active required for Actions REST), so this skill doesn't take that path.
**XML element ordering does NOT affect deploy success** — Salesforce parses and re-serializes canonically. Elements in any order deploy the same.
**Whitespace/indentation does NOT affect deploy success** — normalized before parsing.
**Deploying a Flow with `<status>Draft</status>` does NOT overwrite the Active version** — the existing Active version stays live. This is why our post-verify retrieves and asserts Active: a Draft deploy that "succeeds" skills the org in a state where the CLI invocation still hits the previous Active version, giving misleading test results.
## Common deploy failures + translations
| Salesforce error | Skill translation | Fix |
|---|---|---|
| `INVALID_TYPE: Flow` | Flow metadata not enabled | Rare; usually indicates an org edition without Flow Builder. Escalate. |
| `The apiVersion X is not valid for this API version` | Flow XML `<apiVersion>` > org's API | Lower the Flow's `<apiVersion>` to ≤ the org's current version |
| `Invalid element name` / `was not expected` | Schema mismatch | Check element ordering and spelling against v66 Metadata API docs; some elements are strictly ordered |
| `INSUFFICIENT_ACCESS_OR_READONLY` | User lacks Metadata API deploy permissions | Re-auth as System Administrator, or grant Manage Flows + Deploy From Metadata API |
| `The version of the flow you're trying to activate isn't the latest version` | Someone deployed a newer draft in parallel | Retrieve the newer version, merge, redeploy |
| `You can't deploy flow XXX because it references field YYY` | Flow references a field that doesn't exist on the org | Deploy the field first, or edit the flow to remove the reference |
## Retrieve semantics
`sf project retrieve start --metadata "Flow:<DN>"` returns one XML file. Typically completes in ~2–5s (much faster than the presence-status ~4m 51s retrieve because Flow metadata is a single file, not a packaged set).
**Retrieved XML may not byte-match deployed XML** — Salesforce serializes flow elements in canonical order, which may differ from what you deployed. Grep for `<status>Active</status>` (structural) rather than diffing whole files.
## Standard vs custom flows
Orgs on Service Cloud typically ship with these standard Omni routing flows out of the box:
- `Standard_Omni_Routing_Flow` (if Omni-Channel is enabled)
- Various `Case_*` demo flows depending on Sales Cloud starter templates
Our `Omni_Route_Cases` is a custom addition — it won't collide, but it also won't be invoked by the platform automatically. To wire it into a queue's routing, register it via `service-omni-queue-routing-config-deploy` with `routing_flow_developer_name=Omni_Route_Cases`.
**Naming convention rule:** never use a Flow DeveloperName that starts with `Standard_` — reserved by Salesforce. Our skill uses `Omni_Route_<sObject>` prefix to stay clear of the standard namespace.
## Notes on API version selection
The Actions REST endpoint accepts any recent API version (`v58.0`+ has been stable for autolaunched flow invocation). The deploy script uses `sf org display --json | jq -r '.result.apiVersion'` to pick the org's current API version at runtime rather than hardcoding — this way a v70+ org gets v70 endpoints without a redeploy of the skill.
If the org's reported `apiVersion` is malformed (rare), the script falls back to `66.0` (the Flow XML's declared version).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |