Field Service Data Capture Migrate

Migrate Field Service Mobile Flows to Data Capture

This skill migrates legacy Field Service mobile flows (processType='FieldServiceMobile') to DataCaptureFlow using a fully automated XML transformer. The transformer handles all known migration patterns including field type conversion, execution graph restructuring, variable deduplication, and platform-event removal.

Goal: Get Field Service customers off Mobile Screen Flows and onto Data Capture — the strategic direction for Field Service digital forms.

SKILL_ROOT="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/field-service-data-capture-migrate}"
SCR="$SKILL_ROOT/scripts"
OUT="${FSM_OUT:-$PWD}"  # *_DC files land in cwd; override via FSM_OUT.

Why migrate

Automated migration workflow

Step 0 — Clarify migration scope FIRST

Before querying the org, determine the user's intent. If the request is ambiguous (e.g. "migrate flows", "migrate my org's flows"), ask explicitly whether they mean one specific flow, several named flows, or ALL Field Service Mobile flows in the org. Only proceed to Step 1 after the scope is clear. Never query all flows unless the user explicitly wants that.

Step 1 — Discover flows

REST API endpoint: GET /services/data/v67.0/tooling/query, auth via Authorization: Bearer <token>. Use curl --config — -H leaks via ps//proc.

# All Field Service Mobile flows:
# SOQL: SELECT Id, MasterLabel, ProcessType, Status, VersionNumber FROM Flow
#       WHERE ProcessType = 'FieldServiceMobile' AND Status IN ('Active','Draft')
#       ORDER BY MasterLabel, VersionNumber DESC
curl -X GET "https://<instance>.my.salesforce.com/services/data/v67.0/tooling/query?q=SELECT+Id%2C+MasterLabel%2C+ProcessType%2C+Status%2C+VersionNumber+FROM+Flow+WHERE+ProcessType+%3D+%27FieldServiceMobile%27+AND+Status+IN+%28%27Active%27%2C%27Draft%27%29+ORDER+BY+MasterLabel%2C+VersionNumber+DESC" \
  --config <(printf 'header = "Authorization: Bearer %s"\n' "$TOKEN")

# One or more named flows — add: AND MasterLabel IN ('Work Order Wizard', 'Asset Inspection')

Response format:

{
  "size": 2, "totalSize": 2, "done": true,
  "records": [
    {"Id": "301xx000000001", "MasterLabel": "Asset Inspection", "ProcessType": "FieldServiceMobile", "Status": "Active", "VersionNumber": 5}
  ]
}

URL-encoding: space → +/%20, '→%27, ,→%2C, (/)→%28/%29, =→%3D.

Surface the query results to the user (table or list). If the user named specific flows and any are missing, report that immediately.

Step 2 — Retrieve flow XML

Handed the flow file(s) directly, no org? Skip Steps 1–2 — run Step 4 on each in place (subflows first, --is-subflow), writing <Name>_DC.flow-meta.xml to the current dir, then skip Steps 5–6 (org-only). Otherwise retrieve from the org:

mkdir -p /tmp/fsm-migration/project && cd /tmp/fsm-migration/project
echo '{"packageDirectories":[{"path":"force-app","default":true}],"namespace":"","sourceApiVersion":"67.0"}' > sfdx-project.json

# Single flow:
sf project retrieve start --metadata "Flow:<FlowApiName>" --target-org <alias>
# Multiple (comma-separated, no spaces after commas):
sf project retrieve start --metadata "Flow:<Flow1>,Flow:<Flow2>" --target-org <alias>
# All flows (ONLY if the user explicitly confirmed "all" in Step 0):
sf project retrieve start --metadata "Flow" --target-org <alias>

Critical: --metadata must match the user's Step 0 selection — never retrieve all flows unless explicitly confirmed. (No REST equivalent exists yet for this step — see references/architecture-notes.md.)

Step 3 — Validate migration candidates

Only flows with BOTH FieldServiceMobile processType AND at least one <screens> element are valid candidates:

migratable=()
for f in force-app/main/default/flows/*.flow-meta.xml; do
  base=$(basename "$f" .flow-meta.xml)
  if grep -q "FieldServiceMobile" "$f"; then
    if grep -q "<screens>" "$f"; then
      echo "[MIGRATABLE] $base"; migratable+=("$f")
    else
      echo "[NO SCREENS] $base — cannot migrate (pure automation flow)"
    fi
  else
    processType=$(grep -oP '(?<=<processType>)[^<]+' "$f" || echo "unknown")
    echo "[NOT FSM] $base — processType is '$processType'"
  fi
done | sort
echo "Migratable flows: ${#migratable[@]}"

If the user specified particular flows and any fail validation, STOP and report the issue — don't proceed with partial migration unless the user confirms skipping the invalid ones. If the user confirmed "migrate all", this filters to the migratable subset — report counts before proceeding. Pure automation flows (no <screens>) should stay as-is or become AutoLaunched flows; flag but don't migrate them.

Step 3b — Resolve the subflow dependency tree (composed flows)

Flows that call subflows must migrate leaves-first — a caller can't validate until every _DC subflow it references exists in the deploy set:

python3 "$SCR/discover_subflow_tree.py" \
  force-app/main/default/flows \
  force-app/main/default/flows/<CallerFlowApiName>.flow-meta.xml \
  --json /tmp/fsm-migration/subflow-tree.json

Use the JSON order array as the transform order for Step 4 and the file list for Step 5.

Step 4 — Transform each flow

OUT="${FSM_OUT:-$PWD}"; mkdir -p "$OUT"
# Input: the retrieved project path below, or just <FlowApiName>.flow-meta.xml if handed the file.
python3 "$SCR/transform_flow.py" \
  force-app/main/default/flows/<FlowApiName>.flow-meta.xml \
  "$OUT/<FlowApiName>_DC.flow-meta.xml"

Pass --is-subflow for every node the Step 3b tree reports at depth > 0. A DataCaptureFlow subflow cannot contain Create/Update/Delete — --is-subflow excises CUD unconditionally (not just reordering it) and routes CUD fault-path violations through the fault-severing pre-pass; the plain treatment is correct only for the top-level caller (depth == 0). Skipping it on a real subflow reproduces the "You can't use Create, Update, or Delete elements in a Data Capture flow subflow" deploy failure Step 3b prevents.

Use python3 "$SCR/subflow_names.py" <FlowApiName> to derive the correct output filename — for overridden names a plain _DC suffix won't match the caller's rewritten reference and the bundle dry-run will fail.

The transformer reports fields converted, CUD fixes, and warnings. Unsupported elements (Apex/action calls, subflows, fault paths, custom components, unknown field types) produce an _incompleteMigration list and an <!-- INCOMPLETE MIGRATION ... --> XML comment; unsupported field slots become read-only DisplayText placeholders, never silent ShortText inputs.

Batch transform in parallel — each flow's transform is independent, so use a bounded xargs -P4 instead of a sequential loop. When Step 3b produced subflow-tree.json, look up each flow's depth there to decide whether to add --is-subflow; a flow absent from the tree (no composed dependencies) is always the top-level caller:

OUT="${FSM_OUT:-$PWD}"; mkdir -p "$OUT"
TREE=/tmp/fsm-migration/subflow-tree.json
find force-app/main/default/flows -maxdepth 1 -name '*.flow-meta.xml' -print0 \
  | while IFS= read -r -d '' f; do
      grep -q "FieldServiceMobile" "$f" && grep -q "<screens>" "$f" && printf '%s\0' "$f"
    done \
  | xargs -0 -I{} -P4 bash -c '
      f="{}"; base=$(basename "$f" .flow-meta.xml)
      dcname=$(python3 "'"$SCR"'/subflow_names.py" "$base")
      subflowFlag=""
      if [ -f "'"$TREE"'" ]; then
        depth=$(jq -r --arg n "$base" "(.order[] | select(.apiName == \$n) | .depth) // 0" "'"$TREE"'")
        [ "$depth" -gt 0 ] 2>/dev/null && subflowFlag="--is-subflow"
      fi
      python3 "'"$SCR"'/transform_flow.py" "$f" "'"$OUT"'/${dcname}.flow-meta.xml" $subflowFlag 2>&1 \
        | grep -E "(Transformed|SKIPPED|CUD|Warning)"
    '

Safe even for a composed tree — each transform reads no leaf output (one flow in, one flow out), so nothing needs sequencing here; the leaves-first order from Step 3b only matters for the Step 5 bundle dry-run.

Output name collisions: two source flows must never resolve to the same dcname via subflow_names.py — under -P4 that's a concurrent write to the same file. If the batch has any name overrides, spot-check afterward: find "${FSM_OUT:-$PWD}" -maxdepth 1 -name '*_DC.flow-meta.xml' | sort | uniq -d.

Step 4b — Generate migration summary

SUM=/tmp/fsm-migration/summaries; mkdir -p $SUM /tmp/fsm-migration/spec
find force-app/main/default/flows -maxdepth 1 -name '*.flow-meta.xml' -print0 \
  | while IFS= read -r -d '' f; do
      grep -q "FieldServiceMobile" "$f" && grep -q "<screens>" "$f" && printf '%s\0' "$f"
    done \
  | xargs -0 -I{} -P4 bash -c '
      f="{}"; base=$(basename "$f" .flow-meta.xml)
      python3 "'"$SCR"'/convert_to_dc_spec.py" "$f" "/tmp/fsm-migration/spec/${base}.json"
      python3 "'"$SCR"'/generate_summary.py" \
        "/tmp/fsm-migration/spec/${base}.json" \
        "'"$SUM"'/${base}-migration-summary.md"
    '

The summary lists the component mapping ([OK]/[WARNING]/[ERROR] prefixes), conditional-logic decisions, unsupported components, behavioral notes, an offline-priming warning, a manual Review Checklist, and a clearly-labeled Advisory placeholder (the only place AI-generated prose belongs). generate_summary.py is deterministic and always writes this .md — it's both the input to the canvas in Step 4c and the offline fallback artifact.

Step 4c — Ask how to deliver the review, then publish

Ask explicitly, if interactive — never silently default: "Post the migration summary to Slack, or download it as an .md file?" The per-flow .md from Step 4b exists either way; this only decides whether a Slack canvas also gets created.

• Slack: ask for the destination channel and wait for it — never create a canvas without one (offer a remembered channel, but confirm). Canvas creation is the slack_create_canvas MCP tool (Python can't reach it). Per flow: read ${base}-migration-summary.md, strip the leading # Migration Summary: <formTitle> H1 (the canvas takes the title separately), create a canvas titled Migration Summary: <formTitle> with the rest as content, slack_send_message posts its link into the channel, record the URL for Step 7. Remember the channel.
• File download: point to the .md path(s) already written in Step 4b — nothing further to do.

Fallback: no interactive user, or Slack unavailable / canvas errors — skip to the .md path(s); the run succeeds either way.

Step 5 — Validate (dry-run)

Optional, non-destructive pre-deploy gate — only when an org alias is available. Ask before running (costs wall-clock, not required for output; offline runs skip it and still succeed): "Run dry-run validation against <alias> before deploying? (yes/no)" If the SE declines, treat as exit 3 below: deploy as Draft only (the only status this skill ever deploys).

Default to one bundle dry-run, not one per flow — this lets intra-tree _DC subflow references resolve within the deploy set (an isolated per-flow dry-run fails on a caller whose subflows aren't deployed yet). Fall back to per-flow only if the bundle fails on >1 flow and you need to attribute it:

OUT="${FSM_OUT:-$PWD}"
set --
while IFS= read -r -d '' f; do set -- "$@" "$f"; done \
  < <(find "$OUT" -maxdepth 1 -name '*_DC.flow-meta.xml' -print0)
if [ "$#" -gt 0 ]; then
  "$SCR/validate_flow.sh" --bundle "<alias>" "$@"
  code=$?
  if [ "$code" -eq 1 ] && [ "$#" -gt 1 ]; then
    echo "Bundle dry-run failed — re-running per-flow to attribute the failure(s):"
    "$SCR/validate_flow.sh" "<alias>" "$@"
    code=$?
  fi
else
  echo "No migrated flows to validate."; code=0
fi

In per-flow fallback, a caller referencing _DC subflows fails even when it's fine (its subflow isn't in that isolated deploy set) — treat a flow doesn't exist failure on a known caller as this isolation artifact, not a real defect.

deploy_flow.sh always deploys Draft regardless of dry-run outcome — a failed dry-run just means the deploy isn't worth doing yet.

Optional live smoke test (manual — not in CI). The bundle dry-run proves the script's contract; running it once against a real org proves the output actually deploys:

"$SCR/validate_flow.sh" <org-alias> "${FSM_OUT:-$PWD}/<FlowApiName>_DC.flow-meta.xml"
# Expected: exit 0, "PASS  <FlowApiName>_DC.flow-meta.xml"

Step 6 — Deploy (kickoff + rollback snapshot)

OUT="${FSM_OUT:-$PWD}"
set --
while IFS= read -r -d '' f; do set -- "$@" "$f"; done \
  < <(find "$OUT" -maxdepth 1 -name '*_DC.flow-meta.xml' -print0)

"$SCR/deploy_flow.sh" <alias> "$@"

deploy_flow.sh captures a pre-deploy rollback snapshot of every target flow's prior org state before writing anything, then deploys only after explicit SE confirmation (Proceed? [y/N]; pass --yes to skip for an unattended demo). Every deploy is Draft only — the deploy copy's <status> is force-rewritten to Draft regardless of source content, so nothing here can deploy Active. Activation is the manual Step 8 action.

Rollback snapshot: written to /tmp/fsm-migration/rollback/<timestamp>/snapshot.json, recording per-flow whether it existedBeforeDeploy and (if so) its prior label/active-version/latest-version IDs. To restore, re-deploy the version identified in the snapshot — but confirm no one edited the deployed _DC flow after this deploy, or that edit is lost.

Deploy order: subflows (leaves) before their callers — use the discover_subflow_tree.py order sequence from Step 3b.