@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/field-service-data-capture-migrate/references/fsm-dc-capability-catalog.md

@@ -0,0 +1,215 @@
+# FSM Flow ↔ Data Capture Capability-Parity Catalog
+
+**Authoritative** capability-parity / functionality-gap catalog between Field
+Service Mobile (FSM) Flow and Data Capture (DC) Flow. This document and its
+executable twin — `scripts/fsm_dc_catalog.py` — are the single source of truth
+for the migration skill's supported / unsupported decisions.
+
+It is keyed on the **real FSM Flow component vocabulary** — the standard Flow
+`FlowScreenFieldType` enum (`InputField`, `DropdownBox`, `RadioButtons`,
+`MultiSelectCheckboxes`, `DisplayText`, …) — **not** Lightning component names.
+A `lightning:*` / `forceContent:*` / `c:*` name only ever appears as the
+`<extensionName>` inside a `ComponentInstance` field.
+
+> **Why this rewrite exists (W-23364461):** the skill's earlier
+> supported/unsupported decisions were made against Lightning component names
+> (`lightning:input`, `lightning:fileUpload`, …) rather than the FSM Flow
+> vocabulary the platform actually uses. That produced two concrete errors,
+> corrected below.
+
+---
+
+## Source of truth & verification
+
+Two inputs were reconciled:
+
+1. The **assessment spreadsheet** — *FSM Flow vs Data Capture Flow component
+   assessment*
+   ([sheet](https://docs.google.com/spreadsheets/d/1KeZPHw4AN8XxqxoTh4X9ciLavp9JNcOeYDbSzmCATGg/edit)).
+2. **Salesforce core code** (core-2206, 264 release line), which is
+   authoritative where the two disagree.
+
+Core evidence:
+
+| Fact | Core location |
+|---|---|
+| FSM/DC screen-field vocabulary (`FlowScreenFieldType` enum) | `interaction/.../mdapi/FlowScreenField.java` |
+| FSM's single allowed `ComponentInstance` extension = `forceContent:fileUpload` | `interaction/.../mdapi/validation/FieldServiceMobileFlowValidator.java` (`supportedLightningComponents`) |
+| FSM field types are a **denylist** (blocks only `Component*`/`Region`/`RegionContainer`/`Repeater`/`ObjectProvided`; all native types allowed) | `FieldServiceMobileProcessTypeHandler.hook_isFlowScreenFieldTypeAllowed` |
+| DC field types are an **allowlist** (`DisplayText`, `ComponentInstance`, `ComponentChoice`, `ComponentMultiChoice`, `RegionContainer`, `Region`, `Repeater`, `ObjectProvided`); `AGX_FLOW`-only actions; Offline-only | `interaction/.../mdapi/processtype/DataCaptureFlowProcessTypeHandler.java` |
+
+> **Two different gates — don't conflate them.** FSM screen *field types* are
+> governed by a denylist, so the full native vocabulary (`InputField`,
+> `DropdownBox`, `RadioButtons`, `MultiSelectPicklist`, …) is a valid migration
+> **source**. Separately, an FSM `ComponentInstance` field may embed exactly one
+> whitelisted extension — `forceContent:fileUpload`. DC is the mirror image: it
+> *allows only* the `Component*` field types and blocks the native ones. That
+> asymmetry is why migration is a type **conversion** (`DropdownBox` →
+> `ComponentChoice`+`dcPicklist`), not a pass-through.
+| DC deploy-time ceilings (CUD-at-end, blocked globals, fault stub) | `reference/dc-conditional-logic-sources.md` (spike W-23363833) |
+
+---
+
+## Corrections vs. the assessment spreadsheet
+
+The spreadsheet is correct on almost everything, but core code contradicts it on
+two points that matter for migration decisions:
+
+### 1. Signature is DC-only — FSM has **no** signature component (spreadsheet correct, earlier skill decision wrong)
+
+Core exposes **no native FSM signature component**. `FieldServiceMobileFlowValidator`
+hardcodes the only allowed screen extension as `forceContent:fileUpload` — there
+is no signature entry anywhere in the FSM path. `dcSignature` is DataCaptureFlow-only.
+
+**Consequence:** the earlier decision recorded in **WI-3 (W-23364096)** —
+"file-upload **and signature** ARE supported Phase-1 migration targets" — is
+**wrong on the signature half** and is reversed here. There is no FSM signature
+source to migrate *from*, so there is nothing to emit as `dcSignature`. Any
+downstream task to "implement signature emission" (WI-7 / W-23364093) should be
+**reverted**.
+
+### 2. File-upload is **NOT** DC-only — the spreadsheet is wrong here, and the earlier skill was wrong too
+
+The spreadsheet lists File Upload as "DC only – file attachment" (no FSM
+equivalent). Core disproves this: `FieldServiceMobileFlowValidator` explicitly
+**allows** `forceContent:fileUpload` inside an FSM flow. So:
+
+- FSM Flow **can** contain file upload — via the extension `forceContent:fileUpload`.
+- That maps cleanly to DC's `dcUpFile`.
+- The earlier skill was *also* wrong, for a different reason: it keyed this off
+  `lightning:fileUpload`, which is not the extension FSM actually allows.
+
+**Consequence:** file-upload **is** a supported migration target — the WI-3
+"file-upload supported" conclusion stands — but the mapping must key off
+`forceContent:fileUpload → dcUpFile`, never `lightning:fileUpload`.
+
+---
+
+## Class 1 — FSM components with a clean FSM → DC mapping
+
+Keyed by the FSM `<fieldType>` (and, for `InputField`, the field's `<dataType>`;
+for `ComponentInstance`, the `<extensionName>`).
+
+| FSM fieldType | Discriminator | → DC fieldType | → extensionName |
+|---|---|---|---|
+| `InputField` | dataType `Boolean` | `ComponentInstance` | `dcCheckbox` — *(see discrepancy)* |
+| `InputField` | dataType `String` | `ComponentInstance` | `dcTextInput` |
+| `InputField` | dataType `Number`/`Double`/`Currency` | `ComponentInstance` | `dcNumeric` |
+| `InputField` | dataType `Date` | `ComponentInstance` | `dcDate` |
+| `InputField` | dataType `DateTime` | `ComponentInstance` | `dcDateTime` |
+| `InputField` | dataType `Email` | `ComponentInstance` | `dcEmail` |
+| `InputField` | dataType `Phone` | `ComponentInstance` | `dcPhone` |
+| `InputField` | dataType `TextArea`/`LongTextArea` | `ComponentInstance` | `dcLongText` |
+| `InputField` | dataType `Picklist` | `ComponentChoice` | `dcPicklist` |
+| `InputField` | dataType `MultiselectPicklist` | `ComponentMultiChoice` | `dcCbGroup` |
+| `DropdownBox` | — | `ComponentChoice` | `dcPicklist` |
+| `RadioButtons` | — | `ComponentChoice` | `dcRbGroup` |
+| `RadioButtonGroup` | — | `ComponentChoice` | `dcRbGroup` |
+| `MultiSelectCheckboxes` | — | `ComponentMultiChoice` | `dcCbGroup` |
+| `MultiSelectPicklist` | — | `ComponentMultiChoice` | `dcCbGroup` *(or `dcPicklist` multi-mode)* |
+| `LargeTextArea` | — | `ComponentInstance` | `dcLongText` |
+| `DisplayText` | — | `DisplayText` | *(pass-through)* |
+| `ComponentInstance` | ext `forceContent:fileUpload` | `ComponentInstance` | `dcUpFile` |
+| `ComponentInstance` | ext `forceContent:imageUpload` | `ComponentInstance` | `dcUpImage` |
+| `ComponentInstance` | ext already `runtime_service_fieldservice:dc*` | *(pass-through, cleaned)* | — |
+
+`DisplayText` is the only field type valid in **both** flow types.
+
+## Class 2 — FSM components with **NO DC equivalent** (cannot auto-migrate)
+
+The migration must **flag, never silently drop or downgrade** these.
+
+| FSM fieldType | Why no DC path | Manual option |
+|---|---|---|
+| `PasswordField` | No DC password component | Capture as `dcTextInput` only if non-secret, else drop |
+| `DisplayRichText` | No DC rich-text display | Downgrade to `DisplayText`; rich formatting lost |
+| `PlainButtons` | **DC has no action buttons** (capability gap) | Remove or redesign — no migration path |
+| `ComponentInstance` ext `runtime_industries_csv_dataimport:advCsv` ("**Advanced CSV Import**"), or `:impBeg` (beginner variant) | Industries CSV Data Import / DPE-backed bulk import; DC has no CSV/bulk-import screen component and uses a per-record form model | Rebuild the data-loading step outside the flow (Data Processing Engine) or drop it |
+| `ComponentInstance` w/ any custom ext (`c:*`, `lightning:*` other than the whitelisted `forceContent:fileUpload`) | DC has no custom-component extension point | Rebuild with a native `dc*` component or flag as unmigratable |
+
+> **"Advanced CSV Import" is real — and a gap.** It is a standard-shipped
+> Lightning flow screen component (`runtime_industries_csv_dataimport:advCsv`,
+> `<target>lightning__FlowScreen</target>`) that appears in the FSM flow builder
+> palette when Industries CSV Data Import is enabled, so it can legitimately show
+> up in an FSM source flow. It has no DC equivalent. The catalog names it
+> explicitly (`KNOWN_UNSUPPORTED_EXTENSIONS` in `fsm_dc_catalog.py`) so the gap
+> report says *what* it is rather than a generic "unknown component" (W-23364461).
+
+> **Choice types are NOT gaps.** `MultiSelectPicklist`, `RadioButtonGroup`,
+> `RadioButtons`, `DropdownBox`, and `MultiSelectCheckboxes` all have genuine DC
+> equivalents (Class 1). DC expresses multi-select through the
+> `ComponentMultiChoice` field type — `dcCbGroup`, or `dcPicklist` in multi mode
+> (its meta declares both `allowSingleChoice` and `allowMultipleChoices`). An
+> earlier version of this catalog wrongly listed `MultiSelectPicklist` and
+> `RadioButtonGroup` as no-DC-equivalent; that was a false gap and is corrected
+> here (W-23364461).
+
+## Class 3 — DC-only components (no FSM source maps to them)
+
+These exist only in Data Capture; nothing in a source FSM flow produces them.
+Listed for completeness so the skill can explain what a migration *cannot*
+generate.
+
+| DC component | Notes |
+|---|---|
+| `dcSignature` | Signature capture — **FSM has no signature component** |
+| `dcEmail` / `dcPhone` / `dcName` | Dedicated inputs (FSM approximates via `InputField`) |
+| `dcAddress` | Address input (optional GPS) |
+| `dcLookup` | Record lookup |
+| `dcMatrix` | Matrix / grid input |
+| `dcCounter` | Numeric stepper |
+| `dcCheckbox` | Single checkbox — distinct from Boolean/Toggle (see discrepancy) |
+| `dcFileView` | Read-only file/image viewer |
+| `dcUpImage` | Image upload (dedicated component) |
+| `Region` / `RegionContainer` | Layout regions — FSM disallows |
+| `Repeater` | Native repeating section — FSM used Loop + screens |
+| `ObjectProvided` | Object-provided fields — FSM disallows |
+
+> **`dcImages` does not exist.** Image upload is `dcUpImage`; the read-only
+> file/image viewer is `dcFileView`. (Correction to an earlier assumption.)
+
+---
+
+## Capability-level gaps (beyond individual components)
+
+These are differences no per-component mapping can preserve. They are returned
+by `fsm_dc_catalog.capability_gaps()` and surfaced per-flow by `analyze_flow.py`.
+
+| Capability gap | Detail | Core evidence |
+|---|---|---|
+| **No actions / buttons** | DC has no user-facing action buttons. FSM's `PlainButtons` has no DC equivalent; the only invocable action DC permits is `AGX_FLOW`. | `DataCaptureFlowProcessTypeHandler`: `allowedScreenFieldTypes` omits `PlainButtons`; `allowedActionTypes = {AGX_FLOW}` |
+| **Offline-only** | DC runs only in the Offline environment. Online-only behaviour cannot be preserved. | `hook_isEnvironmentAllowed` → Offline only |
+| **No Apex / action calls** | DC forbids `<actionCalls>` and Apex data types. | action allowlist = `AGX_FLOW` only |
+| **CUD only at end of flow** | All create/update/delete must follow the last screen. FSM allowed CUD mid-flow. | `DataCaptureFlowValidator` CUD-at-end BFS |
+| **No fault paths** | Fault connectors unsupported; FSM fault handling is stripped. | empty `navigateToFault()` stub; blocked `$Flow.FaultMessage` |
+| **Subflows: DC-type only, no CUD** | A DC flow can only call another DC flow, and subflows cannot contain CUD. | subflow-type check |
+| **Inverted gate w/ non-invertible condition** | An inverted-shape gate (default branch shows the field, rule branch skips it) collapses by *negating* the rule condition. When the rule uses a non-invertible operator (`Contains`, `StartsWith`, `EndsWith` — no negated Flow operator) or a custom `conditionLogic` formula, it cannot collapse and stays a flagged decision. Expressing it would need formula-typed visibility. | Flow operator enum has no `DoesNotContain`/`NotStartsWith`/`NotEndsWith`; DC visibility is show-when-only with no per-condition `NOT`. |
+
+---
+
+## Known discrepancy — Boolean `InputField` target (`dcCheckbox` vs `dcToggle`)
+
+The shipping transformer (`transform_flow.py`) maps `InputField`/`Boolean` →
+`dcCheckbox`, and this catalog matches it so **catalog and code stay in sync**
+(AC#5). The assessment spreadsheet instead recommends `dcToggle` for a Boolean
+("Boolean/Toggle is `dcToggle`, **NOT** `dcCheckbox`; single Checkbox is a
+distinct DC-only component").
+
+Both `dcCheckbox` and `dcToggle` bind to a Boolean and deploy successfully — the
+difference is UX (checkbox vs. toggle switch), not correctness. This is an
+**unresolved product decision**, not a bug. If the mapping should change to
+`dcToggle`, update `INPUTFIELD_BY_DATATYPE` in `fsm_dc_catalog.py` **and**
+`FIELD_TYPE_MAP` in `transform_flow.py` together.
+
+---
+
+## How the catalog is consumed
+
+- **`scripts/fsm_dc_catalog.py`** — `classify(field_type, data_type, extension_name)`
+  returns `{status, dc_extension, dc_field_type, note}`; `capability_gaps()`
+  returns the table above; `is_gap(status)` is the gap predicate.
+- **`scripts/analyze_flow.py`** — classifies every screen field via the catalog
+  and emits a **Data Capture Gap Report** per flow (feeds WI-7 / WI-10).
+- **`scripts/transform_flow.py`** — the shipping transformer; its `FIELD_TYPE_MAP`
+  is the same vocabulary and must stay in sync with this catalog.
+- **`reference/component-mapping.md`** — points here as the source of truth.

package/skills/field-service-data-capture-migrate/references/known-deploy-errors.md

@@ -0,0 +1,36 @@
+# Known deploy errors and fixes
+
+These were encountered in real migration runs. All are handled automatically by `transform_flow.py` unless noted.
+
+| Deploy error | Root cause | Fix |
+|---|---|---|
+| `You can't specify the field API Version` | `<apiVersion>` tag present | Removed by transformer |
+| `Element variables is duplicated at this location` | Legacy flow has `ParentRecordId` (capital P); transformer adds `parentRecordId` (lowercase) | Case-insensitive dedup — updates existing var to `isInput=true` instead of adding |
+| `Element inputParameters is duplicated at this location` | Two separate `<inputParameters>` blocks on same field with other elements between them | Reorder field children so all `<inputParameters>` are contiguous — done by transformer |
+| `Flows of type "Data Capture Flow" can't include "RadioButtons"` | `RadioButtons` fieldType not valid in DC | Converted to `ComponentChoice` + `dcRbGroup` by transformer |
+| `Flows of type "Data Capture Flow" can't include "MultiSelectCheckboxes"` | Same | Converted to `ComponentMultiChoice` + `dcCbGroup` |
+| `Outputs aren't supported for fieldType "ComponentChoice"` | `<dataType>` or `<defaultValue>` present on a ComponentChoice field | Removed by transformer |
+| `extensionName is required when fieldType is ComponentChoice` | `extensionName` was removed trying to fix above | Transformer keeps `extensionName` = `dcPicklist`/`dcRbGroup`/`dcCbGroup` on ComponentChoice |
+| `extensionName isn't supported` on Repeater | `extensionName` set on the Repeater element itself | Removed by transformer; only valid on nested fields inside the Repeater |
+| `Data Capture Flows can't use API entities that don't show up in the UI` | `recordCreates` targeting a platform event object | Removed by transformer; predecessors redirected to successor |
+| `The field "X" isn't compatible with the LightningComponentOutput element "Y"` | `<defaultValue>` on a ComponentInstance field | Removed by transformer; use `value` inputParameter instead |
+| `In a Decision Outcome, a condition doesn't support "X" Equals` | Decision condition references a screen component name bare (without `.value`) | Transformer appends `.value` |
+| `Append multiple Create, Update, or Delete operations only at the end of the flow` | CUD node has a non-CUD successor | Graph restructurer hoists the non-CUD successor before first screen |
+| `A loop that contains CUD elements can't include other elements except Assignments` | Screen inside a loop body | Cannot be auto-fixed — requires Repeater redesign |
+| `invalid cross reference id` | Connector target references a removed node | Dangling connectors removed by transformer |
+| `The flow X doesn't exist` (subflow reference) | Subflow name updated to `_DC` suffix but that flow isn't deployed yet | Resolved by dependency ordering: run `discover_subflow_tree.py` (Step 3b) to get the leaves-first order, transform in that order, and bundle-validate (`validate_flow.sh --bundle`) so intra-tree refs resolve |
+| `A required input parameter is missing: 'label'` | `ComponentInstance` field is missing the `label` inputParameter | Transformer moves label from `<fieldText>` to `label` inputParameter |
+| `We can't find this input attribute: "placeholder"` | `placeholder` not supported in DC | Stripped by transformer — bake text into label |
+| `We can't find this input attribute: "helpText"` | `helpText` not supported in DC | Stripped by transformer — bake text into label |
+| `We can't find this input attribute: "min"` / `"max"` on dcNumeric | `min`/`max` only valid on `dcCounter`, not `dcNumeric` | Stripped by transformer; switch to `dcCounter` if numeric constraints are needed |
+| `We can't find this input attribute: "minimumDate"` / `"maximumDate"` | Correct attributes are `minDate` / `maxDate` | Replaced by transformer |
+| `We can't find this input attribute: "multiSelection"` | Correct attribute is `isMultiSelection` | Replaced by transformer |
+| `We can't find this input attribute: "disabled"` / `"readOnly"` on Lookup | Correct: `isDisabled` / `isReadonly` (lowercase `o`) | Replaced by transformer |
+| `We can't find this input attribute: "recordIds"` on Lookup | Correct: `recordIdCollection` | Replaced by transformer |
+| `'Range' is not a valid value for the enum 'FlowScreenFieldType'` | Slider (`Range`) not valid in DataCaptureFlow | Flagged by transformer as SKIPPED — replace manually with `dcNumeric` or `dcCounter` |
+| `This flow can't reference [X] because the referenced flow type is Autolaunched Flow` | Calling an AutoLaunched subflow from DataCaptureFlow | Not auto-fixable; inline the logic or convert subflow to DataCaptureFlow |
+| `storeOutputAutomatically field isn't supported` on Repeater | `storeOutputAutomatically` must not be on the Repeater itself | Transformer omits it on the Repeater; only nested fields inside the Repeater get it |
+| `Element X is duplicated at this location` (non-inputParameters) | XML elements of same type are not in a contiguous block | Reorder the XML so all same-type elements are grouped |
+| `Error while resolving default value reference` *(runtime — not deploy)* | Complex formula in `DisplayText` (`IF`, `CASE`, date math) | Transformer warns; pre-calculate in Assignment → reference simple variable in DisplayText |
+| `isRequired=true` blocks hidden field *(runtime — not deploy)* | Required check fires even when field is hidden behind `visibilityRule` | Transformer warns; manually clear `isRequired` and add `validationRule` |
+| `outputAssignments` in `dynamicChoiceSets` populates blank *(runtime — not deploy)* | `outputAssignments` inside choice sets deploys but does NOT populate variables at mobile runtime | Replace with post-selection `recordLookups` using `outputAssignments` |

package/skills/field-service-data-capture-migrate/references/migration-checklist.md

@@ -0,0 +1,121 @@
+# Data Capture Migration Checklist
+
+Step-by-step manual validation checklist for migrated flows.
+
+## Pre-Migration
+
+- [ ] **Identify candidate flows** — `SELECT Id, ApiName, Label, ProcessType FROM FlowDefinition WHERE ProcessType = 'FieldServiceMobile'` (Tooling API)
+- [ ] **Retrieve legacy flow XML** — `sf project retrieve start --metadata Flow:<FlowApiName> --target-org <alias>`
+- [ ] **Run analysis script** — `python3 "$SCR/analyze_flow.py" /tmp/<FlowApiName>.flow-meta.xml /tmp/<FlowApiName>_analysis.json`
+- [ ] **Review risk score and manual steps** (from analysis output)
+- [ ] **Decision: GREEN → automate, YELLOW → review spec, RED → manual redesign**
+
+## Migration Phase
+
+- [ ] **Run converter** — `python3 "$SCR/convert_to_dc_spec.py" /tmp/<FlowApiName>.flow-meta.xml /tmp/<FlowApiName>_dc_spec.json`
+- [ ] **Review generated spec**
+  - Field types are correct; choice mappings for picklists/radios are valid
+  - No `_migrationNote` fields requiring manual config; check `_automationNote` for postScreen automation
+- [ ] **Adjust spec as needed** — add `lookupObject` for Lookup fields, `fileName` for FileView fields, simplify flagged visibility rules, convert Apex-dependent logic to record lookups
+- [ ] **Build Data Capture flow** — `python3 "$SCR/vendor/build_flow.py" /tmp/<FlowApiName>_dc_spec.json <FlowApiName>_v2 /tmp/<FlowApiName>_v2.flow-meta.xml`
+- [ ] **Deploy to org** — `"$SCR/deploy_flow.sh" <alias> /tmp/<FlowApiName>_v2.flow-meta.xml`
+- [ ] **Verify deploy success** — `SELECT ApiName, ProcessType FROM FlowDefinition WHERE ApiName = '<FlowApiName>_v2'` (Tooling API)
+
+## Post-Deploy Validation
+
+### Desktop Testing
+
+- [ ] **Open Flow Builder** for the deployed flow — verify screens render, field properties (type, label, required, visibility) are correct, and automation elements (decisions, loops, record operations) behave as expected
+- [ ] **Direct flow launch test** at `<instanceUrl>/flow/<FlowApiName>_v2` — complete the form end-to-end, verify all screens display, required validation and conditional visibility work, and submit succeeds
+- [ ] **Verify record creation/update** — query the target object for records created `WHERE CreatedDate = TODAY`, confirm structure matches expectations
+
+### Briefcase & Offline Priming
+
+- [ ] **Add objects/fields to Briefcase** — Setup → Briefcase Builder; add every object/field the flow reads or writes, assign to the test user
+- [ ] **Verify priming** — run as the test user in the User simulator; confirm the primed record count is reasonable
+
+### Mobile Testing
+
+- [ ] **Attach to test parent record** — this skill does not script this step (it would be a data-record write, out of the deploy-metadata-only scope). Attach the migrated form to a test parent record (ServiceAppointment/WorkOrder/etc.) manually via Setup's Data Capture assignment UI before continuing.
+- [ ] **Verify Forms tab prerequisites** — all three must pass before the form appears on FSL Mobile:
+  - `DynamicDataCapture` and `WorkPlan` internal sharing model (`EntityDefinition.InternalSharingModel`) must be `ReadWrite`, not `Private`
+  - `FieldServiceSettings.DoesShareSaWithAr__c` and `DoesShareSaParentWoWithAr__c` must both be `true`
+  - If any setting changed, re-save affected `AssignedResource` records so the new sharing rules apply
+- [ ] **Device: sign out + back in** (required after any OWD/sharing change above)
+- [ ] **Device: open parent record → Forms tab** — verify the migrated form appears and opens with all screens rendering
+- [ ] **Device: complete form online** — fill all fields, exercise required validation and visibility rules, submit, verify the success message
+- [ ] **Device: verify data persisted** — query the target object for today's records
+- [ ] **Device: enable airplane mode → complete form offline** — fill and submit; verify it queues as a draft with a "queued" indicator
+- [ ] **Device: disable airplane mode, wait ~30s for sync, then verify the queued record synced** — query the target object again
+
+### Comparison Testing
+
+- [ ] **Create a test parent record** (e.g. Work Order)
+- [ ] **Complete the LEGACY flow on record A** — note fields populated and records created
+- [ ] **Complete the MIGRATED flow on record B** — note fields populated and records created
+- [ ] **Diff the two outcomes** — field values, record counts, and relationships must match; no data loss
+
+### Edge Cases & Stress Tests
+
+- [ ] **All decision branches** — walk each conditional path, verify correct screen routing
+- [ ] **Visibility rules** — toggle controlling fields, verify dependents show/hide correctly
+- [ ] **Repeater (if present)** — add, edit, and delete rows; verify the `.AllItems` loop creates the correct records
+- [ ] **Lookup (if present)** — search, select, verify downstream references resolve
+- [ ] **File/signature/image components (if present)** — capture/upload, verify `ContentDocument` and its `ContentDocumentLink` to the parent are created
+- [ ] **Validation rules** — submit with missing required fields and with invalid data; confirm both are blocked with the correct error message
+
+## Production Cutover
+
+- [ ] **Final smoke test** on the migrated flow
+- [ ] **Communicate to users** — notify technicians, provide a side-by-side comparison if useful, set a cutover date
+- [ ] **Monitor for issues** — failed drafts in the sync queue, support tickets, data quality
+- [ ] **Deactivate the legacy flow** (after the soak period)
+- [ ] **Remove the `_v2` suffix** (optional) — clone with the production name, repoint DDC attachments, delete the `_v2` version
+- [ ] **Clean up test records**
+
+## Rollback Plan
+
+If critical issues are found:
+
+- [ ] **Deactivate the migrated flow** (Flow Builder)
+- [ ] **Reactivate the legacy flow**
+- [ ] **Repoint DDC attachments** back to the legacy flow — update `DynamicDataCapture.ActionDefinition` to `<LegacyFlowApiName>`
+- [ ] **Notify users of the rollback**
+- [ ] **Root cause analysis** — review failed drafts, check error logs, identify missing config (Briefcase, FLS, OWD, etc.)
+- [ ] **Fix and retry** — adjust the spec, rebuild as `_v3`, repeat this checklist
+
+## Documentation
+
+- [ ] **Update org documentation** — migration date, differences from the legacy version, training materials
+- [ ] **Archive the legacy flow** — export XML to source control with a README explaining the migration
+- [ ] **Tag the migrated flow** — note in Flow Builder that it's a migrated version, referencing the original flow name
+
+## Success Criteria
+
+Migration is successful when:
+
+1. All screens render correctly on mobile
+2. All fields accept input and validate correctly
+3. Conditional logic works (visibility, routing)
+4. Record operations succeed (creates/updates)
+5. Offline mode works (drafts queue and sync)
+6. Data integrity matches legacy flow output
+7. No user-reported critical issues for 1 week
+8. Form appears reliably in FSL Mobile "Forms" tab
+9. Performance is acceptable (form loads < 2 sec)
+10. Technicians can complete the form without errors
+
+## Common Issues & Fixes
+
+| Issue | Likely Cause | Fix |
+|-------|--------------|-----|
+| Form doesn't appear in Forms tab | DDC/WorkPlan OWD is Private | Set to ReadWrite, re-save AssignedResources, sign out/in on device |
+| Field missing on mobile | Not in Briefcase | Add object/field to Briefcase Builder |
+| Lookup returns no results | `lookupObject` not configured | Add to spec and redeploy |
+| File upload fails | `parentRecordId` not wired | Converter should auto-wire; verify XML |
+| Visibility rule doesn't work | Formula too complex for DC | Simplify or move to Assignment + simple condition |
+| Draft never syncs | Validation rule blocks insert | Fix validation rule or adjust form data |
+| Form renders blank | Custom component not converted | Replace with native DC component |
+| Create fails with "field required" | `isRequired` not set on field | Add to spec or in Flow Builder |
+| Multiple rows not created | Repeater `.AllItems` loop incorrect | Verify loop references `RepeaterName.AllItems`, not `RepeaterName` |
+| Cross-screen reference broken | Formula in DisplayText not supported | Move to Assignment between screens |

package/skills/field-service-data-capture-migrate/references/transformer-rules.md

@@ -0,0 +1,132 @@
+# What the transformer does automatically
+
+`transform_flow.py` is a direct XML-to-XML transformer — no spec generation, no intermediate files. It makes one pass through the flow and applies all transformations below.
+
+## Field type conversion (complete mapping)
+
+| Legacy fieldType | Legacy dataType / extensionName | → DC fieldType | → extensionName |
+|---|---|---|---|
+| `InputField` | `Boolean` | `ComponentInstance` | `dcCheckbox` |
+| `InputField` | `String` | `ComponentInstance` | `dcTextInput` |
+| `InputField` | `Number` / `Double` / `Currency` | `ComponentInstance` | `dcNumeric` |
+| `InputField` | `Date` | `ComponentInstance` | `dcDate` |
+| `InputField` | `DateTime` | `ComponentInstance` | `dcDateTime` |
+| `InputField` | `Email` | `ComponentInstance` | `dcEmail` |
+| `InputField` | `Phone` | `ComponentInstance` | `dcPhone` |
+| `InputField` | `TextArea` / `LongTextArea` | `ComponentInstance` | `dcLongText` |
+| `InputField` | `Picklist` | `ComponentChoice` | `dcPicklist` (supports single OR multiple selection via configuration) |
+| `InputField` | `MultiselectPicklist` | `ComponentMultiChoice` | `dcCbGroup` |
+| `InputField` | `Name` | `ComponentInstance` | `dcName` |
+| `InputField` | `Toggle` | `ComponentInstance` | `dcToggle` |
+| `InputField` | `Address` | `ComponentInstance` | `dcAddress` |
+| `InputField` | `Lookup` | `ComponentInstance` | `dcLookup` |
+| `InputField` | `Counter` | `ComponentInstance` | `dcCounter` |
+| `InputField` | `Matrix` | `ComponentMultiChoice` | `dcMatrix` |
+| `DropdownBox` | — | `ComponentChoice` | `dcPicklist` |
+| `RadioButtons` | — | `ComponentChoice` | `dcRbGroup` |
+| `RadioButtonGroup` | — | `ComponentChoice` | `dcRbGroup` |
+| `MultiSelectCheckboxes` | — | `ComponentMultiChoice` | `dcCbGroup` |
+| `MultiSelectPicklist` | — | `ComponentMultiChoice` | `dcCbGroup` |
+| `LargeTextArea` | — | `ComponentInstance` | `dcLongText` |
+| `forceContent:fileView` | — | `ComponentInstance` | `dcFileView` |
+| `forceContent:fileUpload` | — | `ComponentInstance` | `dcUpFile` |
+| `forceContent:imageUpload` | — | `ComponentInstance` | `dcUpImage` |
+| `Range` (slider) | — | **SKIPPED — not valid in DC** | Flag for manual replacement with `dcNumeric` or `dcCounter` |
+| `DisplayText` | — | `DisplayText` | *(pass-through)* |
+| `Repeater` | — | `Repeater` | *(pass-through)* |
+| Already `runtime_service_fieldservice:dc*` | — | *(pass-through, cleaned)* | — |
+
+## Required XML injected on every converted ComponentInstance field
+
+Every `dc*` `ComponentInstance` field gets these elements injected by the transformer:
+
+```xml
+<inputsOnNextNavToAssocScrn>UseStoredValues</inputsOnNextNavToAssocScrn>
+<storeOutputAutomatically>true</storeOutputAutomatically>
+<styleProperties>
+    <verticalAlignment><stringValue>top</stringValue></verticalAlignment>
+    <width><stringValue>12</stringValue></width>
+</styleProperties>
+```
+
+**Exception:** `<fieldType>Repeater</fieldType>` must NOT get `storeOutputAutomatically` — the Repeater always outputs via `.AllItems` and the element causes a deploy error if present on the Repeater itself (nested fields inside the Repeater still get it).
+
+## Label placement rules by fieldType
+
+| fieldType | Label location | Note |
+|---|---|---|
+| `ComponentInstance` (`dc*`) | `<inputParameters><name>label</name>...` | `<fieldText>` is stripped if present; missing `label` inputParameter causes deploy error |
+| `ComponentChoice` / `ComponentMultiChoice` | `<fieldText>` | Direct content |
+| `DisplayText` | `<fieldText>` | HTML content |
+| `RegionContainer` / `Region` (section) | `<fieldText>` | Section header |
+
+## CUD-at-end graph restructuring
+
+DataCaptureFlow requires all record creates/updates/deletes after the last screen. The transformer detects violations by walking the execution graph and fixes them with 4 patterns (up to 50 convergence iterations):
+
+**Analysis/converter path (WI-8):** `convert_to_dc_spec.py` and `analyze_flow.py` perform
+ordinal CUD-placement analysis (`scripts/cud_analysis.py`): each create/update/delete is
+classified by execution position as `compliant`, `safe_consolidate`, or `unsafe_manual`.
+Safe record-creates are auto-consolidated into `postScreen.recordCreates` (rendered after
+the last screen); unsafe CUD and safe updates/deletes (no auto-move path) get precise
+manual-restructure guidance in `_cudAnalysis` / `_migrationSummary`. This is distinct from
+the `transform_flow.py` restructurer, which rewrites the flow XML connectors in place.
+
+- **Pattern A — CUD → Screen**: Moves the screen to before the CUD chain (converts "confirmation after save" to "confirm before save")
+- **Pattern B — CUD → Lookup**: Hoists the lookup to before the first screen (pre-loads data before user sees the form)
+- **Pattern C — CUD → Assignment**: Same as Pattern B
+- **Pattern D — CUD → Decision**: Hoists the decision to before the first screen
+
+**Functional impact of CUD restructuring:** In most flows, lookups that were originally after a screen are pre-screen in the original design anyway (they load context). Hoisting them doesn't change their results. **Check the warnings output** — if a warning says a hoisted lookup filters on a screen field value, that lookup will run with an empty value before the user fills in the screen. That flow needs manual redesign.
+
+## Other automatic fixes
+
+- `processType` → `DataCaptureFlow`
+- `status` → `Draft` (always — the source's status, often `Active`, never leaks through; `deploy_flow.sh` also force-rewrites `<status>` to `Draft` at the deploy boundary, so this holds even for a hand-edited file. Activation is a manual admin action in the org UI after a clean dry-run and device testing — SKILL.md Step 8 — never scripted)
+- `environments` → `Offline` (replaces `Default` or adds if missing)
+- Sets `areMetricsLoggedToDataCloud` to `false` (required DC header; adds if missing, updates if present)
+- Removes `<apiVersion>` (not valid in DC — causes deploy error if present)
+- Removes `<constants>` (not allowed in DC)
+- Removes `<actionCalls>` elements (not allowed in DC — use DisplayText for notifications)
+- Strips fault connectors from all elements (not supported in DataCaptureFlow)
+- Removes platform event `<recordCreates>` nodes (DC can't create non-UI entities like `AsgnResourceLocUpdateEvent`) — **side effect: those events will no longer fire**
+- Removes `<outputAssignments>` from screen fields → replaced with `storeOutputAutomatically=true` + an injected `<assignments>` node to preserve variable bindings
+- Strips invalid `<inputParameters>`: `required`, `disabled`, `multiple`, `accept`, `helpText`, `placeholder` (none supported in DC; bake content into label text instead)
+- Replaces `minimumDate`/`maximumDate` with `minDate`/`maxDate` on date fields
+- Replaces `multiSelection` with `isMultiSelection` on Lookup fields
+- Replaces `disabled`/`readOnly` with `isDisabled`/`isReadonly` (note lowercase `o`) on Lookup fields
+- Replaces `recordIds` inputParameter with `recordIdCollection` on Lookup fields
+- Removes `extensionName` from Repeater elements (only valid on nested fields inside a Repeater)
+- Removes `min`/`max` inputParameters from `dcNumeric` fields (only valid on `dcCounter`)
+- Fixes screen field references in downstream automation to use `{fieldName}.value` (DC accessor pattern)
+- Removes `<defaultValue>` from `ComponentInstance` fields (DC uses `value` inputParameter instead)
+- Removes `<dataType>` from `ComponentChoice` fields
+- Removes dangling empty connectors left by restructuring
+- Case-insensitive deduplication of `<variables>` — updates `isInput=true` on existing vars rather than adding duplicates
+- Ensures required DC input variables: `recordId`, `parentRecordId`, `parentObjectType` (all String, `isInput=true`)
+- Ensures required screen attributes: `allowFinish`, `showFooter`, `nextOrFinishButtonLabel`
+- Reorders field child elements so all `<inputParameters>` are contiguous (fixes "Element inputParameters is duplicated" deploy error)
+- Updates subflow `<flowName>` references to DC versions (appends `_DC` suffix; explicit overrides for known name mismatches)
+- **Detects and warns** (does NOT auto-fix): Screen inside a loop — DC doesn't support screens in loops; requires Repeater redesign
+- **Detects and warns** (does NOT auto-fix): `Range` slider fields — not valid in DataCaptureFlow; replace manually with `dcNumeric` or `dcCounter`
+- **Detects and warns** (does NOT auto-fix): `isRequired=true` on fields behind a `visibilityRule` — required check fires even when field is hidden; mobile worker cannot proceed
+- **Detects and warns** (does NOT auto-fix): complex formulas in `DisplayText` fields (`IF`, `CASE`, date math) — deploys fine but fails at mobile runtime
+
+---
+
+# Functional equivalence after migration
+
+**What is preserved exactly:**
+- All record lookups, creates, updates, deletes (just reordered to comply with DC constraint)
+- All decisions, loops, assignments
+- All screen fields and their labels
+- All choice sets (picklists, radio groups, checkboxes)
+- All visibility rules
+- All variable definitions (deduplicated)
+- All subflow calls (references updated to DC names)
+
+**What changes behaviorally:**
+- **Lookup execution order**: Lookups hoisted before the first screen now run before the user sees the form. Most lookups load context data (Work Order details, parent records) and are unaffected. Lookups that filter on screen input values will run with empty inputs — transformer flags these in warnings.
+- **Platform events removed**: Any `recordCreates` targeting event objects (e.g. `AsgnResourceLocUpdateEvent`) are removed. Real-time dispatcher/Gantt events that were fired mid-flow will no longer fire. If this matters, replace with an Apex trigger or a separate AutoLaunched flow triggered by the record update.
+- **Confirmation screens**: If the original flow showed a confirmation screen *after* saving a record (Pattern A), the DC version shows it *before*. The data is still saved — the order of user experience changes.
+- **Constants replaced**: Flow constants are removed (DC doesn't support them). Downstream references to constants may need to be replaced with hardcoded values or variables.