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 |
scripts/deploy-and-report.sh
View on GitHub#!/usr/bin/env bash
# deploy-and-report.sh - deploy + verify an Omni routing Flow: autolaunched dryRun smoke flow (default, verified via Actions REST) or record-triggered production flow (--trigger, token-resolved, optional --runtime-proof). Args, token resolution, exit codes: SKILL.md.
set -euo pipefail
# Escape the five XML predefined entities so a ServiceChannel MasterLabel with & < > " ' cannot
# corrupt the flow XML when substituted into the asset below.
xml_escape() {
local s="$1"
s="${s//&/&}"; s="${s//</<}"; s="${s//>/>}"; s="${s//\"/"}"; s="${s//\'/'}"
printf '%s' "$s"
}
# Escape sed replacement metacharacters (\ & and the | delimiter) so an escaped value is inserted
# literally by the sed substitution.
sed_repl_escape() { printf '%s' "$1" | sed -e 's/[\\&|]/\\&/g'; }
if [ $# -lt 1 ]; then
echo '{"error":"Missing required argument: org-alias","usage":"bash deploy-and-report.sh <org-alias> [flow_developer_name] [--skip-invoke] [--target Case|VoiceCall] [--trigger] [--runtime-proof]"}' >&2
exit 1
fi
# --- Parse flags out of the arg list, leaving positional args intact ---
SKIP_INVOKE="false"
TRIGGER_MODE="false"
RUNTIME_PROOF="false"
# --require-proof (or OMNI_RUNTIME_PROOF_REQUIRED=1): make runtime routing proof mandatory (a missing
# PendingServiceRouting|AgentWork blocks instead of fail-soft); the Voice release gate. Implies --runtime-proof.
REQUIRE_PROOF="${OMNI_RUNTIME_PROOF_REQUIRED:-0}"
[ "$REQUIRE_PROOF" = "1" ] && { REQUIRE_PROOF="true"; RUNTIME_PROOF="true"; TRIGGER_MODE="true"; } || REQUIRE_PROOF="false"
TARGET="Case"
# Routing type for the record-triggered production flow: QueueBased (default, backward-compatible) or
# SkillsBased. SkillsBased selects the skills-based flow variant (${FLOW_DN}.SkillsBased.flow-meta.xml)
# and REQUIRES a non-null skillOption - a null skillOption makes the platform routeWork action NPE and
# roll back the triggering insert (W-24069761).
ROUTING_TYPE="${OMNI_ROUTING_TYPE:-QueueBased}"
# skillOption for SkillsBased routing (ignored for QueueBased). RunSBRRules (default) makes the platform
# evaluate the org's WorkSkillRouting rules server-side and attach matching SkillRequirement rows;
# DefineSkillRequirements uses only skills the flow passes; Both does both. Closed set - mirrors
# OmniFlowConstants.SkillOption in core.
SKILL_OPTION="${OMNI_SKILL_OPTION:-RunSBRRules}"
SKILL_OPTION_EXPLICIT="false"
POSITIONAL=()
while [ $# -gt 0 ]; do
case "$1" in
--skip-invoke) SKIP_INVOKE="true" ;;
--trigger) TRIGGER_MODE="true" ;;
--runtime-proof) RUNTIME_PROOF="true"; TRIGGER_MODE="true" ;;
--require-proof) REQUIRE_PROOF="true"; RUNTIME_PROOF="true"; TRIGGER_MODE="true" ;;
--target) shift; TARGET="${1:-Case}" ;;
--target=*) TARGET="${1#*=}" ;;
--routing-type) shift; ROUTING_TYPE="${1:-}" ;;
--routing-type=*) ROUTING_TYPE="${1#*=}" ;;
--skill-option) shift; SKILL_OPTION="${1:-}"; SKILL_OPTION_EXPLICIT="true" ;;
--skill-option=*) SKILL_OPTION="${1#*=}"; SKILL_OPTION_EXPLICIT="true" ;;
*) POSITIONAL+=("$1") ;;
esac
shift
done
set -- "${POSITIONAL[@]}"
ORG="$1"
case "$TARGET" in
Case) DEFAULT_SMOKE_FLOW="Omni_Route_Cases"; DEFAULT_TRIGGER_FLOW="Omni_Route_Case_Trigger"; DEFAULT_SC_DEVNAME="Cases" ;;
VoiceCall) DEFAULT_SMOKE_FLOW="Omni_Route_VoiceCalls"; DEFAULT_TRIGGER_FLOW="Omni_Route_VoiceCall_Trigger"; DEFAULT_SC_DEVNAME="sfdc_phone" ;;
*) echo "{\"error\":\"Invalid --target '$TARGET'. Supported: Case, VoiceCall\"}" >&2; exit 2 ;;
esac
case "$ROUTING_TYPE" in
QueueBased|SkillsBased) ;;
*) echo "{\"error\":\"Invalid --routing-type '$ROUTING_TYPE'. Supported: QueueBased, SkillsBased\"}" >&2; exit 2 ;;
esac
# 761 guard: a SkillsBased routeWork with a null/invalid skillOption NPEs in the platform action and
# rolls back the triggering insert. Refuse to emit one - the skill never ships a null skillOption.
if [ "$ROUTING_TYPE" = "SkillsBased" ]; then
case "$SKILL_OPTION" in
RunSBRRules|DefineSkillRequirements|Both) ;;
"") echo "{\"error\":\"routing-type SkillsBased requires a non-empty --skill-option (RunSBRRules|DefineSkillRequirements|Both). Refusing to deploy a SkillsBased routeWork flow with a null skillOption: it would NPE in the platform action and roll back the triggering insert (W-24069761).\"}" >&2; exit 2 ;;
*) echo "{\"error\":\"Invalid --skill-option '$SKILL_OPTION'. Supported: RunSBRRules, DefineSkillRequirements, Both\"}" >&2; exit 2 ;;
esac
fi
if [ "$ROUTING_TYPE" = "QueueBased" ] && [ "$SKILL_OPTION_EXPLICIT" = "true" ]; then
echo '{"error":"--skill-option is valid only with --routing-type SkillsBased."}' >&2
exit 2
fi
# Flow to operate on: explicit positional wins; else target+mode default.
if [ "$TRIGGER_MODE" = "true" ]; then
FLOW_DN="${2:-$DEFAULT_TRIGGER_FLOW}"
else
FLOW_DN="${2:-$DEFAULT_SMOKE_FLOW}"
fi
if ! [[ "$FLOW_DN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
echo "{\"error\":\"Invalid flow_developer_name '$FLOW_DN'. Must start with a letter, only A-Z a-z 0-9 _ (max 80).\"}" >&2
exit 1
fi
if ! [[ "$ORG" =~ ^[A-Za-z0-9._@-]{1,128}$ ]]; then
echo "{\"error\":\"Invalid org alias '$ORG'.\"}" >&2
exit 1
fi
if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
echo "{\"error\":\"Org alias '$ORG' is not authenticated.\"}" >&2
exit 1
fi
# Write guard: deploys Flow metadata, so self-enforce the production-org guard (directly invokable).
ORG_GUARD_JSON=$(sf data query --target-org "$ORG" \
--query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" \
--json 2>/dev/null) || {
echo "{\"error\":\"Failed to query Organization for safe_to_write guard: $(printf '%s' "$ORG_GUARD_JSON" | head -c 300)\"}" >&2
exit 1
}
IS_SANDBOX=$(echo "$ORG_GUARD_JSON" | jq -r '.result.records[0].IsSandbox')
TRIAL_EXP=$(echo "$ORG_GUARD_JSON" | jq -r '.result.records[0].TrialExpirationDate // "null"')
ORG_TYPE=$(echo "$ORG_GUARD_JSON" | jq -r '.result.records[0].OrganizationType')
SAFE_TO_WRITE=false
if [ "$IS_SANDBOX" = "true" ] \
|| [ "$TRIAL_EXP" != "null" ] \
|| [ "$ORG_TYPE" = "Developer Edition" ] \
|| [ "$ORG_TYPE" = "Base Edition" ]; then
SAFE_TO_WRITE=true
fi
if [ "$SAFE_TO_WRITE" != "true" ]; then
echo "{\"skill\":\"service-omni-routing-flow-deploy\",\"status\":\"blocked\",\"blocking_issue\":\"Refusing to deploy Flow metadata to a real production customer org (IsSandbox=$IS_SANDBOX, TrialExpirationDate=$TRIAL_EXP, OrganizationType=$ORG_TYPE). Target a sandbox, trial CDO, or Developer Edition org.\",\"safe_to_write\":false}" >&2
exit 1
fi
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
ASSETS_DIR="$(cd "$SCRIPT_DIR/../assets" && pwd)"
FLOW_XML="$ASSETS_DIR/force-app/main/default/flows/${FLOW_DN}.flow-meta.xml"
# Template the deploy reads from. The SkillsBased trigger variant is a sibling asset carrying
# routingType=SkillsBased + a non-null skillOption; QueueBased and the smoke/dryRun flows use the base
# asset. Either way the temp copy is written as ${FLOW_DN}.flow-meta.xml, so the deployed DeveloperName
# stays $FLOW_DN (the SkillsBased flow REPLACES the QueueBased one - never two triggers on one object).
TEMPLATE_XML="$FLOW_XML"
if [ "$TRIGGER_MODE" = "true" ] && [ "$ROUTING_TYPE" = "SkillsBased" ]; then
TEMPLATE_XML="$ASSETS_DIR/force-app/main/default/flows/${FLOW_DN}.SkillsBased.flow-meta.xml"
fi
if [ ! -f "$ASSETS_DIR/sfdx-project.json" ]; then
echo "{\"error\":\"Assets DX project not found at $ASSETS_DIR\"}" >&2
exit 1
fi
if [ ! -f "$TEMPLATE_XML" ]; then
echo "{\"error\":\"Flow asset not found at $TEMPLATE_XML. Add the .flow-meta.xml file, or pick a different flow_developer_name / --routing-type.\"}" >&2
exit 1
fi
# Resolve the org's API version so we hit the right Actions REST endpoint. The Flow metadata
# is written at 66.0 but the org may serve a newer API - the endpoint takes any recent version.
API_VERSION=$(sf org display --target-org "$ORG" --json 2>/dev/null \
| jq -r '.result.apiVersion // "66.0"')
if ! [[ "$API_VERSION" =~ ^[0-9]+\.[0-9]+$ ]]; then
API_VERSION="66.0"
fi
# TRIGGER MODE - deploy the record-triggered production flow (token-resolved), then optionally prove
# routing at runtime. Self-contained: emits its own report and exits.
if [ "$TRIGGER_MODE" = "true" ]; then
# Cleanup on EVERY exit path: remove the temp DX project + delete any throwaway proof record.
TWORK=""
CLEANUP_RECORD_ID=""
_rf_cleanup() {
[ -n "$TWORK" ] && rm -rf "$TWORK" 2>/dev/null || true
if [ -n "$CLEANUP_RECORD_ID" ]; then
sf data delete record --target-org "$ORG" --sobject "$TARGET" --record-id "$CLEANUP_RECORD_ID" >/dev/null 2>&1 || true
fi
}
trap _rf_cleanup EXIT
trigger_blocked() {
jq -n --arg flow "$FLOW_DN" --arg target "$TARGET" --arg msg "$1" \
'{skill:"service-omni-routing-flow-deploy", status:"blocked", mode:"record_triggered",
target:$target, flow_developer_name:$flow, flow_active:false,
runtime_proof:{attempted:false,success:false,reason:"blocked_before_proof"},
manual_actions:[], blocking_issue:$msg}'
exit 1
}
# --- Resolve the Queue bound to the target sObject ---
QDN="${QUEUE_DEVELOPER_NAME:-}"
if [ -n "$QDN" ] && ! [[ "$QDN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
trigger_blocked "Invalid QUEUE_DEVELOPER_NAME '$QDN'."
fi
if [ -z "$QDN" ]; then
QSO=$(sf data query --target-org "$ORG" \
--query "SELECT QueueId, Queue.DeveloperName FROM QueueSobject WHERE SobjectType='$TARGET' ORDER BY Queue.DeveloperName" --json 2>/dev/null)
QSO_DNS=$(echo "$QSO" | jq -c '[.result.records[].Queue.DeveloperName] | unique' 2>/dev/null || echo '[]')
QSO_N=$(echo "$QSO_DNS" | jq 'length' 2>/dev/null || echo 0)
if [ "$QSO_N" = "0" ]; then
trigger_blocked "No queue is bound to '$TARGET'. Run service-omni-queue-deploy --create-if-missing first, or set QUEUE_DEVELOPER_NAME."
elif [ "$QSO_N" != "1" ]; then
trigger_blocked "Multiple queues bound to '$TARGET' ($QSO_DNS). Set QUEUE_DEVELOPER_NAME to disambiguate."
fi
QDN=$(echo "$QSO_DNS" | jq -r '.[0]')
fi
Q_JSON=$(sf data query --target-org "$ORG" \
--query "SELECT Id, QueueRoutingConfigId FROM Group WHERE DeveloperName='$QDN' AND Type='Queue'" --json 2>/dev/null)
QUEUE_ID=$(echo "$Q_JSON" | jq -r '.result.records[0].Id // empty')
[ -z "$QUEUE_ID" ] && trigger_blocked "Queue '$QDN' not found on org."
QUEUE_RC_ID=$(echo "$Q_JSON" | jq -r '.result.records[0].QueueRoutingConfigId // empty')
# --- Resolve the QueueRoutingConfig ---
RC_DN="${ROUTING_CONFIG_DEVELOPER_NAME:-}"
if [ -n "$RC_DN" ] && ! [[ "$RC_DN" =~ ^[A-Za-z][A-Za-z0-9_]{0,79}$ ]]; then
trigger_blocked "Invalid ROUTING_CONFIG_DEVELOPER_NAME '$RC_DN'."
fi
if [ -z "$RC_DN" ] && [ -n "$QUEUE_RC_ID" ]; then
RC_DN=$(sf data query --target-org "$ORG" \
--query "SELECT DeveloperName FROM QueueRoutingConfig WHERE Id='$QUEUE_RC_ID'" --json 2>/dev/null \
| jq -r '.result.records[0].DeveloperName // empty')
fi
if [ -z "$RC_DN" ]; then
case "$TARGET" in
VoiceCall) RC_DN="Voice_Routing_Config" ;;
*) RC_DN="Case_Routing_Config" ;;
esac
fi
RC_ID=$(sf data query --target-org "$ORG" \
--query "SELECT Id FROM QueueRoutingConfig WHERE DeveloperName='$RC_DN'" --json 2>/dev/null \
| jq -r '.result.records[0].Id // empty')
[ -z "$RC_ID" ] && trigger_blocked "QueueRoutingConfig '$RC_DN' does not exist. Run service-omni-queue-routing-config-deploy (QRC_ROUTING_TARGET=$TARGET) first, or set ROUTING_CONFIG_DEVELOPER_NAME."
# --- Resolve the ServiceChannel (Tooling API), FAIL CLOSED if absent ---
# The flow embeds the ServiceChannel Id in routeWork; an empty id would deploy a flow routing
# nothing. The coordinator passes the discovered channel via SERVICE_CHANNEL_DEVELOPER_NAME.
SC_DN="${SERVICE_CHANNEL_DEVELOPER_NAME:-$DEFAULT_SC_DEVNAME}"
if [ -n "$SC_DN" ] && ! [[ "$SC_DN" =~ ^[A-Za-z0-9_]{1,80}$ ]]; then
trigger_blocked "Invalid SERVICE_CHANNEL_DEVELOPER_NAME '$SC_DN'."
fi
SC_TOOLING=$(sf data query --target-org "$ORG" --use-tooling-api \
--query "SELECT Id, MasterLabel FROM ServiceChannel WHERE DeveloperName='$SC_DN'" --json 2>/dev/null || echo '{}')
SC_ID=$(echo "$SC_TOOLING" | jq -r '.result.records[0].Id // empty')
SC_LABEL=$(echo "$SC_TOOLING" | jq -r '.result.records[0].MasterLabel // empty')
if [ -z "$SC_ID" ]; then
trigger_blocked "ServiceChannel '$SC_DN' not found on org (Tooling API returned no row). For $TARGET run service-omni-service-channel-configure (sobject_type=$TARGET) first - the standard Voice channel is 'sfdc_phone' - or set SERVICE_CHANNEL_DEVELOPER_NAME to an existing channel. Refusing to deploy a flow with an unresolved ServiceChannel."
fi
[ -z "$SC_LABEL" ] && SC_LABEL="$SC_DN"
# --- PLAN_ONLY: report the resolution, do not write ---
if [ "${PLAN_ONLY:-}" = "1" ]; then
jq -n --arg flow "$FLOW_DN" --arg target "$TARGET" --arg q "$QDN" --arg rc "$RC_DN" --arg sc "$SC_DN" \
--arg routing_type "$ROUTING_TYPE" --arg skill_option "$SKILL_OPTION" \
'{skill:"service-omni-routing-flow-deploy", status:"action_needed", plan_mode:true, mode:"record_triggered",
target:$target, flow_developer_name:$flow, routing_type:$routing_type,
skill_option:(if $routing_type=="SkillsBased" then $skill_option else null end),
resolved:{queue:$q, routing_config:$rc, service_channel:$sc},
plan_detail:("Would deploy record-triggered \($routing_type) flow \($flow) binding queue \($q), QRC \($rc), channel \($sc)" + (if $routing_type=="SkillsBased" then " with skillOption \($skill_option)." else "." end)),
manual_actions:[], blocking_issue:null}'
exit 0
fi
# --- Idempotency guard with stale-binding detection ---
# A Flow deploy always mints a new version, so re-runs would grow the version count. If an active
# version exists AND its embedded queue/QRC/channel Ids still match, report "reused" and skip;
# if the bindings have drifted, redeploy. OMNI_FLOW_FORCE=1 always redeploys.
EXISTING_ACTIVE=$(sf data query --target-org "$ORG" --use-tooling-api \
--query "SELECT Id FROM Flow WHERE Definition.DeveloperName='$FLOW_DN' AND Status='Active' LIMIT 1" --json 2>/dev/null \
| jq -r '.result.records[0].Id // empty')
BINDINGS_MATCH="false"
if [ -n "$EXISTING_ACTIVE" ]; then
RWORK="$(mktemp -d)"
cp "$ASSETS_DIR/sfdx-project.json" "$RWORK/sfdx-project.json"
mkdir -p "$RWORK/force-app/main/default"
( cd "$RWORK" && sf project retrieve start --target-org "$ORG" --metadata "Flow:${FLOW_DN}" --json >/dev/null 2>&1 || true )
ACTIVE_XML=$(find "$RWORK" -name "${FLOW_DN}.flow-meta.xml" 2>/dev/null | head -1)
if [ -n "$ACTIVE_XML" ] && [ -f "$ACTIVE_XML" ]; then
# Resource bindings and routing semantics must all match. Without the routing-mode checks, a
# QueueBased flow with current IDs could be incorrectly reused for a SkillsBased request.
if grep -qF "$QUEUE_ID" "$ACTIVE_XML" 2>/dev/null \
&& grep -qF "$RC_ID" "$ACTIVE_XML" 2>/dev/null \
&& grep -qF "$SC_ID" "$ACTIVE_XML" 2>/dev/null \
&& grep -qF "<stringValue>${ROUTING_TYPE}</stringValue>" "$ACTIVE_XML" 2>/dev/null \
&& { [ "$ROUTING_TYPE" != "SkillsBased" ] \
|| grep -qF "<stringValue>${SKILL_OPTION}</stringValue>" "$ACTIVE_XML" 2>/dev/null; }; then
BINDINGS_MATCH="true"
fi
fi
rm -rf "$RWORK"
fi
if [ -n "$EXISTING_ACTIVE" ] && [ "$BINDINGS_MATCH" = "true" ] && [ "${OMNI_FLOW_FORCE:-0}" != "1" ]; then
TRIG_STATUS="reused"
TSTATE="Unchanged"
else
# --- Substitute tokens into a temp copy of the asset and deploy ---
TWORK="$(mktemp -d)"
mkdir -p "$TWORK/force-app/main/default/flows"
cp "$ASSETS_DIR/sfdx-project.json" "$TWORK/sfdx-project.json"
SC_LABEL_SED="$(sed_repl_escape "$(xml_escape "$SC_LABEL")")"
sed \
-e "s|__SERVICE_CHANNEL_ID__|${SC_ID}|g" \
-e "s|__SERVICE_CHANNEL_DEVNAME__|${SC_DN}|g" \
-e "s|__SERVICE_CHANNEL_LABEL__|${SC_LABEL_SED}|g" \
-e "s|__ROUTING_CONFIG_ID__|${RC_ID}|g" \
-e "s|__QUEUE_ID__|${QUEUE_ID}|g" \
-e "s|__SKILL_OPTION__|${SKILL_OPTION}|g" \
"$TEMPLATE_XML" > "$TWORK/force-app/main/default/flows/${FLOW_DN}.flow-meta.xml"
TDEPLOY=$(cd "$TWORK" && sf project deploy start --target-org "$ORG" --metadata "Flow:${FLOW_DN}" --json 2>/dev/null || true)
TDEPLOY_OK=$(echo "$TDEPLOY" | jq -r '.result.success // false' 2>/dev/null)
if [ "$TDEPLOY_OK" != "true" ]; then
TERR=$(echo "$TDEPLOY" | jq -r '.result.details.componentFailures // [] | map(.problem) | join("; ")' 2>/dev/null)
[ -z "$TERR" ] || [ "$TERR" = "null" ] && TERR=$(echo "$TDEPLOY" | jq -r '.message // "Unknown deploy error"' 2>/dev/null)
trigger_blocked "Record-triggered flow deploy failed: $TERR"
fi
TSTATE=$(echo "$TDEPLOY" | jq -r --arg fn "$FLOW_DN" '.result.files[] | select(.fullName==$fn and .type=="Flow") | .state' 2>/dev/null | head -1)
TSTATE="${TSTATE:-unknown}"
TRIG_STATUS="reused"
case "$TSTATE" in Created) TRIG_STATUS="created";; Changed) TRIG_STATUS="updated";; Unchanged) TRIG_STATUS="reused";; *) trigger_blocked "Deploy ok but Flow state unrecognized ('$TSTATE').";; esac
fi
# --- Round-trip active-version proof ---
# Component state only proves the deploy transaction; a flow with no active version never fires.
# Prefer FlowDefinitionView, then fall back to the Tooling Flow row because an unrelated malformed
# managed-package definition can make FlowDefinitionView fail for the entire org.
TRIG_ACTIVE_VER=$(sf data query --target-org "$ORG" \
--query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='$FLOW_DN'" --json 2>/dev/null \
| jq -r '.result.records[0].ActiveVersionId // ""' 2>/dev/null || echo "")
if [ -z "$TRIG_ACTIVE_VER" ] || [ "$TRIG_ACTIVE_VER" = "null" ]; then
TRIG_ACTIVE_VER=$(sf data query --target-org "$ORG" --use-tooling-api \
--query "SELECT Id FROM Flow WHERE Definition.DeveloperName='$FLOW_DN' AND Status='Active' LIMIT 1" --json 2>/dev/null \
| jq -r '.result.records[0].Id // ""' 2>/dev/null || echo "")
fi
if [ -z "$TRIG_ACTIVE_VER" ] || [ "$TRIG_ACTIVE_VER" = "null" ]; then
trigger_blocked "Record-triggered flow '$FLOW_DN' deployed (state=$TSTATE), but neither FlowDefinitionView nor the Tooling Flow query found an active version, so routing would not fire. Re-run, or activate the flow in Setup → Flows."
fi
# --- Runtime proof (optional): fire the trigger and look for a PendingServiceRouting/AgentWork ---
RP_ATTEMPTED="false"; RP_SUCCESS="false"; RP_REASON=""; RP_RECORD_ID=""; RP_PSR="null"; RP_AW="null"
# SkillsBased acceptance signal: SkillRequirement rows the platform attached to the PSR (the exact
# thing that was missing when routeWork hardcoded QueueBased - W-24069467).
RP_SKILLREQS="null"; RP_SKILLREQ_COUNT="0"
if [ "$RUNTIME_PROOF" = "true" ]; then
RP_ATTEMPTED="true"
case "$TARGET" in
Case) REC=$(sf data create record --target-org "$ORG" --sobject Case --values "Subject='Omni routing proof' Status='New' Origin='Phone'" --json 2>/dev/null || true) ;;
VoiceCall) REC=$(sf data create record --target-org "$ORG" --sobject VoiceCall --values "CallType='Inbound'" --json 2>/dev/null || true) ;;
esac
RP_RECORD_ID=$(echo "$REC" | jq -r '.result.id // empty' 2>/dev/null)
# Register the record for deletion on exit (trap) so the proof never leaves test data behind.
[ -n "$RP_RECORD_ID" ] && CLEANUP_RECORD_ID="$RP_RECORD_ID"
if [ -z "$RP_RECORD_ID" ]; then
RP_REASON="Could not create a $TARGET record to fire the trigger: $(echo "$REC" | jq -r '.message // (.result.errors[0].message) // "unknown"' 2>/dev/null | head -c 240). On orgs without Service Cloud Voice provisioned, VoiceCall is not directly insertable - deploy is proven, runtime proof is not."
else
# Poll for PendingServiceRouting then AgentWork (async). Cadence env-tunable
# (OMNI_PROOF_POLL_TRIES / OMNI_PROOF_POLL_SLEEP); defaults ~30s.
RP_TRIES="${OMNI_PROOF_POLL_TRIES:-6}"
RP_SLEEP="${OMNI_PROOF_POLL_SLEEP:-5}"
for _ in $(seq 1 "$RP_TRIES"); do
PSR=$(sf data query --target-org "$ORG" \
--query "SELECT Id, IsReadyForRouting, RoutingModel FROM PendingServiceRouting WHERE WorkItemId='$RP_RECORD_ID' ORDER BY CreatedDate DESC LIMIT 1" --json 2>/dev/null || echo '{}')
if [ "$(echo "$PSR" | jq -r '.result.totalSize // 0')" != "0" ]; then
RP_PSR=$(echo "$PSR" | jq -c '.result.records[0]')
if [ "$ROUTING_TYPE" = "SkillsBased" ]; then
_psr_id=$(echo "$PSR" | jq -r '.result.records[0].Id')
# SkillRequirement has no SkillLevel column; its skill-strength field is SkillNumber.
SREQ=$(sf data query --target-org "$ORG" \
--query "SELECT Id, SkillId, SkillNumber, IsAdditionalSkill, SkillPriority FROM SkillRequirement WHERE RelatedRecordId='$_psr_id'" --json 2>/dev/null || true)
# A failed query prints error JSON to stdout THEN exits non-zero, so a `|| echo '{}'`
# fallback would concatenate two JSON values and break the downstream --argjson. Validate
# that we captured a single well-formed value and fall back to empty otherwise.
echo "$SREQ" | jq -e . >/dev/null 2>&1 || SREQ='{}'
RP_SKILLREQ_COUNT=$(echo "$SREQ" | jq -r '.result.totalSize // 0' 2>/dev/null || echo 0)
RP_SKILLREQS=$(echo "$SREQ" | jq -c '.result.records // []' 2>/dev/null || echo '[]')
if [ "$RP_SKILLREQ_COUNT" -gt 0 ]; then
RP_SUCCESS="true"
break
fi
else
RP_SUCCESS="true"
break
fi
fi
AW=$(sf data query --target-org "$ORG" \
--query "SELECT Id, Status FROM AgentWork WHERE WorkItemId='$RP_RECORD_ID' ORDER BY CreatedDate DESC LIMIT 1" --json 2>/dev/null || echo '{}')
if [ "$(echo "$AW" | jq -r '.result.totalSize // 0')" != "0" ]; then
RP_AW=$(echo "$AW" | jq -c '.result.records[0]')
if [ "$ROUTING_TYPE" != "SkillsBased" ]; then
RP_SUCCESS="true"
break
fi
fi
sleep "$RP_SLEEP"
done
if [ "$RP_SUCCESS" != "true" ] && [ "$ROUTING_TYPE" = "SkillsBased" ] \
&& [ "$RP_PSR" != "null" ] && [ "$RP_SKILLREQ_COUNT" = "0" ]; then
RP_REASON="A PendingServiceRouting row appeared for record $RP_RECORD_ID, but it has no SkillRequirement rows. SkillsBased runtime proof requires at least one SkillRequirement produced by the active WorkSkillRouting rule."
elif [ "$RP_SUCCESS" != "true" ]; then
RP_REASON="Record $RP_RECORD_ID created but no PendingServiceRouting/AgentWork appeared within the proof window. The flow deployed and is Active; routing may require an online agent, a configured Contact Center, or more time."
fi
fi
fi
# Mandatory-proof gate: when proof is required, a missing PendingServiceRouting|AgentWork blocks.
if [ "$REQUIRE_PROOF" = "true" ] && [ "$RP_SUCCESS" != "true" ]; then
jq -n \
--arg flow "$FLOW_DN" --arg target "$TARGET" --arg state "$TSTATE" --arg active_ver "$TRIG_ACTIVE_VER" \
--arg routing_type "$ROUTING_TYPE" --arg skill_option "$SKILL_OPTION" \
--arg q "$QDN" --arg qid "$QUEUE_ID" --arg rc "$RC_DN" --arg rcid "$RC_ID" --arg sc "$SC_DN" --arg scid "$SC_ID" \
--arg rp_rec "$RP_RECORD_ID" --argjson rp_psr "$RP_PSR" --argjson rp_aw "$RP_AW" --arg rp_reason "$RP_REASON" \
--argjson rp_skillreqs "$RP_SKILLREQS" --arg rp_skillreq_count "$RP_SKILLREQ_COUNT" \
'{skill:"service-omni-routing-flow-deploy", status:"blocked", mode:"record_triggered", target:$target,
flow_developer_name:$flow, flow_state:$state, flow_active:true, flow_active_version_id:$active_ver,
routing_type:$routing_type, skill_option:(if $routing_type=="SkillsBased" then $skill_option else null end),
resolved:{queue:{developer_name:$q,id:$qid}, routing_config:{developer_name:$rc,id:$rcid}, service_channel:{developer_name:$sc,id:(if $scid=="" then null else $scid end)}},
runtime_proof:{attempted:true, required:true, success:false, record_id:(if $rp_rec=="" then null else $rp_rec end), pending_service_routing:$rp_psr, agent_work:$rp_aw, skill_requirement_count:($rp_skillreq_count|tonumber), skill_requirements:(if $routing_type=="SkillsBased" then $rp_skillreqs else null end), reason:(if $rp_reason=="" then null else $rp_reason end)},
manual_actions:[], blocking_issue:("Runtime routing proof REQUIRED but not observed: " + (if $rp_reason=="" then "no PendingServiceRouting/AgentWork appeared" else $rp_reason end) + " (VoiceCall runtime proof needs a provisioned Contact Center + an online agent).")}'
exit 1
fi
jq -n \
--arg status "$TRIG_STATUS" --arg flow "$FLOW_DN" --arg target "$TARGET" --arg state "$TSTATE" --arg active_ver "$TRIG_ACTIVE_VER" \
--arg routing_type "$ROUTING_TYPE" --arg skill_option "$SKILL_OPTION" \
--arg q "$QDN" --arg qid "$QUEUE_ID" --arg rc "$RC_DN" --arg rcid "$RC_ID" --arg sc "$SC_DN" --arg scid "$SC_ID" \
--arg rp_attempted "$RP_ATTEMPTED" --arg rp_success "$RP_SUCCESS" --arg rp_reason "$RP_REASON" \
--arg rp_required "$REQUIRE_PROOF" \
--arg rp_rec "$RP_RECORD_ID" --argjson rp_psr "$RP_PSR" --argjson rp_aw "$RP_AW" \
--argjson rp_skillreqs "$RP_SKILLREQS" --arg rp_skillreq_count "$RP_SKILLREQ_COUNT" \
'{
skill:"service-omni-routing-flow-deploy",
status:$status,
mode:"record_triggered",
target:$target,
flow_developer_name:$flow,
flow_state:$state,
flow_active:true,
flow_active_version_id:$active_ver,
routing_type:$routing_type,
skill_option:(if $routing_type=="SkillsBased" then $skill_option else null end),
resolved:{queue:{developer_name:$q, id:$qid}, routing_config:{developer_name:$rc, id:$rcid}, service_channel:{developer_name:$sc, id:(if $scid=="" then null else $scid end)}},
runtime_proof:{
attempted:($rp_attempted=="true"),
required:($rp_required=="true"),
success:($rp_success=="true"),
record_id:(if $rp_rec=="" then null else $rp_rec end),
pending_service_routing:$rp_psr,
agent_work:$rp_aw,
skill_requirement_count:($rp_skillreq_count|tonumber),
skill_requirements:(if $routing_type=="SkillsBased" then $rp_skillreqs else null end),
reason:(if $rp_reason=="" then null else $rp_reason end)
},
manual_actions:[],
blocking_issue:null
}'
exit 0
fi
# Deploy - explicit --metadata (not --source-dir) so a sibling metadata file can't piggyback.
DEPLOY_JSON=$(cd "$ASSETS_DIR" && sf project deploy start --target-org "$ORG" \
--metadata "Flow:${FLOW_DN}" \
--json 2>/dev/null || true)
DEPLOY_SUCCESS=$(echo "$DEPLOY_JSON" | jq -r '.result.success // false' 2>/dev/null)
DEPLOY_ID=$(echo "$DEPLOY_JSON" | jq -r '.result.id // null' 2>/dev/null)
translate_deploy_error() {
local raw="$1"
case "$raw" in
*INVALID_TYPE*"Flow"*)
echo "Flow metadata type not enabled on this org (unusual - usually indicates the org edition doesn't include Flow Builder)."
;;
*"Flow.*is not valid for this API version"*|*"API version"*)
echo "Flow XML apiVersion or asset version mismatch. Confirm assets/force-app/main/default/flows/${FLOW_DN}.flow-meta.xml <apiVersion> is <= the org's current API version ($API_VERSION)."
;;
*"Invalid element name"*|*"was not expected"*)
echo "Flow XML schema mismatch. The Flow metadata schema is strict; check element ordering and spelling against v66 Metadata API docs."
;;
*INSUFFICIENT_ACCESS*)
echo "Executing user lacks Metadata API deploy permissions. Re-authenticate as a System Administrator or grant Author Apex + Manage Flows."
;;
*)
echo "$raw"
;;
esac
}
if [ "$DEPLOY_SUCCESS" != "true" ]; then
FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.result.details.componentFailures // [] | map(.problem) | join("; ")' 2>/dev/null)
if [ -z "$FAILURES" ] || [ "$FAILURES" = "null" ]; then
FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.message // .result.errorMessage // "Unknown deploy error"' 2>/dev/null)
fi
FRIENDLY=$(translate_deploy_error "$FAILURES")
jq -n \
--arg deploy_id "$DEPLOY_ID" \
--arg flow "$FLOW_DN" \
--arg blocking "$FRIENDLY" \
--arg raw "$FAILURES" \
'{
skill: "service-omni-routing-flow-deploy",
status: "blocked",
flow_developer_name: $flow,
flow_state: "not_deployed",
flow_active: false,
deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
invocation_smoke_test: {attempted: false, success: false, reason: "deploy_failed"},
manual_actions: [],
blocking_issue: $blocking,
raw_error: $raw
}'
exit 1
fi
FLOW_STATE=$(echo "$DEPLOY_JSON" | jq -r --arg fn "$FLOW_DN" \
'.result.files[] | select(.fullName == $fn and .type == "Flow") | .state' 2>/dev/null | head -1)
FLOW_STATE="${FLOW_STATE:-unknown}"
case "$FLOW_STATE" in
Created|Changed|Unchanged) ;;
*)
jq -n \
--arg flow "$FLOW_DN" \
--arg st "$FLOW_STATE" \
--arg deploy_id "$DEPLOY_ID" \
'{
skill: "service-omni-routing-flow-deploy",
status: "blocked",
flow_developer_name: $flow,
flow_state: $st,
flow_active: false,
deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
invocation_smoke_test: {attempted: false, success: false, reason: "unrecognized_component_state"},
manual_actions: [],
blocking_issue: ("Deploy reported success overall but Flow component has an unrecognized/absent state \"" + $st + "\" (expected Created, Changed, or Unchanged).")
}'
exit 1
;;
esac
# Post-verify #1: retrieve the deployed Flow and confirm <status>Active</status> (a flow can deploy
# in Draft/Obsolete - a silent failure, since autolaunched flows must be Active to be CLI-invocable).
VERIFY_WORK="$(mktemp -d)"
trap 'rm -rf "$VERIFY_WORK"' EXIT
cp "$ASSETS_DIR/sfdx-project.json" "$VERIFY_WORK/sfdx-project.json"
mkdir -p "$VERIFY_WORK/force-app/main/default"
# Retrieve for its side effect (writes the flow XML); verified by inspecting the file below.
( cd "$VERIFY_WORK" && sf project retrieve start --target-org "$ORG" \
--metadata "Flow:${FLOW_DN}" --json >/dev/null 2>&1 || true )
RETRIEVED_XML=$(find "$VERIFY_WORK" -name "${FLOW_DN}.flow-meta.xml" 2>/dev/null | head -1)
FLOW_ACTIVE="unverified"
if [ -n "$RETRIEVED_XML" ] && [ -f "$RETRIEVED_XML" ]; then
if grep -qE "<status>Active</status>" "$RETRIEVED_XML"; then
FLOW_ACTIVE="true"
else
FLOW_ACTIVE="false"
fi
fi
if [ "$FLOW_ACTIVE" != "true" ]; then
if [ "$FLOW_ACTIVE" = "false" ]; then
BLOCK_MSG="Flow deployed but not Active on post-verify (the retrieved metadata does not carry <status>Active</status>). The flow XML must declare <status>Active</status> for autolaunched CLI invocation to work."
else
BLOCK_MSG="Flow deployed but the Active-status verification could not be performed (retrieve returned no Flow XML - inconclusive)."
fi
jq -n \
--arg flow "$FLOW_DN" \
--arg st "$FLOW_STATE" \
--arg deploy_id "$DEPLOY_ID" \
--arg active "$FLOW_ACTIVE" \
--arg msg "$BLOCK_MSG" \
'{
skill: "service-omni-routing-flow-deploy",
status: "blocked",
flow_developer_name: $flow,
flow_state: $st,
flow_active: ($active == "true"),
deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
invocation_smoke_test: {attempted: false, success: false, reason: "flow_not_active"},
manual_actions: [],
blocking_issue: $msg
}'
exit 1
fi
# Post-verify #2: invoke the flow via Actions REST with dryRun=true (proves CLI-executability).
# POST /services/data/vXX.X/actions/custom/flow/<FlowDN>, body {"inputs":[{"dryRun":true}]};
# success = [0].isSuccess && [0].outputValues.dryRunOk.
INVOKE_ATTEMPTED="false"
INVOKE_SUCCESS="false"
INVOKE_REASON=""
INVOKE_RAW="{}"
INVOKE_DRY_RUN_OK="false"
if [ "$SKIP_INVOKE" != "true" ]; then
INVOKE_ATTEMPTED="true"
INVOKE_ENDPOINT="/services/data/v${API_VERSION}/actions/custom/flow/${FLOW_DN}"
INVOKE_BODY='{"inputs":[{"dryRun":true}]}'
INVOKE_RAW=$(sf api request rest \
--method POST \
--target-org "$ORG" \
--body "$INVOKE_BODY" \
"$INVOKE_ENDPOINT" \
2>&1 || true)
# sf api request rest (beta) prints a warning line before the JSON body; strip everything up to
# the first line starting with [ or { - that's the actual body.
INVOKE_JSON=$(printf '%s' "$INVOKE_RAW" | awk '/^[[{]/,0')
# Parse the stripped payload (raw array for Actions API, or an error-wrapping object).
if echo "$INVOKE_JSON" | jq -e '.' >/dev/null 2>&1; then
IS_SUCCESS=$(echo "$INVOKE_JSON" | jq -r 'if type == "array" then .[0].isSuccess else .isSuccess // false end' 2>/dev/null)
INVOKE_DRY_RUN_OK=$(echo "$INVOKE_JSON" | jq -r 'if type == "array" then (.[0].outputValues.dryRunOk // false) else (.outputValues.dryRunOk // false) end' 2>/dev/null)
if [ "$IS_SUCCESS" = "true" ] && [ "$INVOKE_DRY_RUN_OK" = "true" ]; then
INVOKE_SUCCESS="true"
else
INVOKE_REASON=$(echo "$INVOKE_JSON" | jq -r '
if type == "array" then
(.[0].errors // []) | map(.message) | join("; ")
else
(.errors // []) | map(.message) | join("; ")
end' 2>/dev/null)
if [ -z "$INVOKE_REASON" ] || [ "$INVOKE_REASON" = "null" ]; then
INVOKE_REASON="Invocation returned isSuccess=$IS_SUCCESS, dryRunOk=$INVOKE_DRY_RUN_OK (expected true/true)."
fi
fi
else
INVOKE_REASON="Actions API returned non-JSON after stripping the sf beta-warning preamble. Raw first 200 chars: $(printf '%s' "$INVOKE_RAW" | head -c 200)"
fi
if [ "$INVOKE_SUCCESS" != "true" ]; then
jq -n \
--arg flow "$FLOW_DN" \
--arg st "$FLOW_STATE" \
--arg deploy_id "$DEPLOY_ID" \
--arg reason "$INVOKE_REASON" \
--argjson raw "$(echo "$INVOKE_JSON" | jq -R -s '.' 2>/dev/null || echo '""')" \
'{
skill: "service-omni-routing-flow-deploy",
status: "blocked",
flow_developer_name: $flow,
flow_state: $st,
flow_active: true,
deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
invocation_smoke_test: {attempted: true, success: false, reason: $reason, raw_response: $raw},
manual_actions: [{id: "INVOCATION_FAILED", title: "Flow deployed & Active but Actions REST invocation failed. Rerun with --skip-invoke to accept deploy-only, or investigate the API response.", endpoint: ("/services/data/v" + "'"$API_VERSION"'" + "/actions/custom/flow/" + $flow)}],
blocking_issue: ("Flow deployed and Active, but invocation via Actions REST failed: " + $reason)
}'
exit 1
fi
fi
# Skill-level status.
STATUS="reused"
case "$FLOW_STATE" in
Created) STATUS="created" ;;
Changed) STATUS="updated" ;;
Unchanged) STATUS="reused" ;;
esac
jq -n \
--arg status "$STATUS" \
--arg flow "$FLOW_DN" \
--arg flow_state "$FLOW_STATE" \
--arg deploy_id "$DEPLOY_ID" \
--arg api_ver "$API_VERSION" \
--arg invoke_attempted "$INVOKE_ATTEMPTED" \
--arg invoke_success "$INVOKE_SUCCESS" \
--arg dry_run_ok "$INVOKE_DRY_RUN_OK" \
'{
skill: "service-omni-routing-flow-deploy",
status: $status,
flow_developer_name: $flow,
flow_state: $flow_state,
flow_active: true,
deploy_id: $deploy_id,
invocation_smoke_test: {
attempted: ($invoke_attempted == "true"),
success: ($invoke_success == "true"),
cli_path: "actions_rest",
endpoint: ("/services/data/v" + $api_ver + "/actions/custom/flow/" + $flow),
dry_run_ok: ($dry_run_ok == "true")
},
manual_actions: [],
blocking_issue: null
}'
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 |