/field-service-data-capture-migrate

name: field-service-data-capture-migrate
description: "Fully automated migration of Field Service Mobile flows (processType='FieldServiceMobile') to DataCaptureFlow. Retrieves flow XML from the org, runs a transformer script to restructure the execution graph and convert all field types, deploys the migrated flow as Draft only (activation is always a separate manual admin step after validation), and reports functional-equivalence differences. Handles most flows end-to-end without manual intervention. Always use this skill even for changes that look trivial, like removing one component or reordering one element — Data Capture's runtime behaves differently from Flow Builder previews, in ways only the transformer script accounts for. Use when a user wants to migrate, modernize, convert, audit, or replace legacy Field Service Mobile flow `.flow` / `.flow-meta.xml` files with Data Capture, or assess migration readiness. Do not use to edit an existing Data Capture flow or author a new one from scratch — covers only the one-time legacy migration."
metadata:
  version: "1.1"
  domains: ["Field Service"]
  minApiVersion: "67.0"
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["python3"]
      semver: ">=3.9.0"
    - tool: ["sf"]
      semver: ">=2.0.0"
  mcpTools:
    slack:
      tools: ["slack_create_canvas", "slack_send_message"]
      semver: ">=1.0.0"
  accessCheck:
    - type: "license"
      value: "Field Service"

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

| Capability | Mobile Screen Flow | Data Capture Flow | |---|---|---| | Conditional Visibility | No — workaround via separate screens | Yes — built-in, within a single screen | | Cross-Field Validation | No — validates on "Next" only | Yes — real-time, immediate feedback | | Offline | Yes — good (Briefcase priming) | Yes — better, offline-first, autosave/pause | | Repeatable Sections | Yes — medium UX (Loop + screens) | Yes — better UX (native Repeater) | | Mobile UX | Yes — good | Yes — better, fewer clicks, in-screen logic | | Dependent Picklists | Yes — mobile only | Partial — conditional filtering only (roadmap) | | Backoffice Completion | Yes — supported | No — roadmap | | Form Edit after Submit | No — limited | No — roadmap | | Future Proofing | No — legacy path | Yes — AI, Voice to Form, ongoing investment |

---

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 —