@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/automation-flow-coordinate/references/recipes/testing/workflows/save-debug.md

@@ -0,0 +1,212 @@
+---
+id: flow.recipes.testing.workflows.save-debug
+description: "Boilerplate WithoutAssertion FlowTest — pin a scenario's inputs as a re-runnable smoke test with no expectations. The assertions-free subset of author-test; for promoting an interactive debug run instead, use promote."
+---
+
+<!-- Consumers: testing router (direct entry when user says "save a smoke test", "no assertions", "just lock in that this passes") -->
+
+# Save a WithoutAssertion smoke test
+
+Use when the user wants to persist a scenario's **inputs** as a
+re-runnable test but has **no expectations to assert** — "just save that
+this flow runs clean for this record", "lock in this input set", "a
+smoke test, no assertions". The output is a `WithoutAssertion` FlowTest:
+a Start binding, `assertions: []`, and nothing else.
+
+This is the assertions-free subset of
+[[flow.recipes.testing.workflows.author-test]]. It exists as its own
+recipe because the boilerplate is small and the user should not be
+walked through assertion-intent ceremony they explicitly don't want.
+
+**Pick a different recipe when:**
+
+- The inputs come from an **interactive debug run** the user just
+  iterated → [[flow.recipes.testing.workflows.promote]] (its Route A
+  with `assertions: []` is this same payload, seeded from debug context).
+- The user **does** want to check an outcome → the full
+  [[flow.recipes.testing.workflows.author-test]].
+
+What "passes" means here: a `WithoutAssertion` test has no assertions to
+fail, so a run succeeds iff the flow completes without a fault. The run
+step still matters — it's what catches a binding that saved clean but
+drives the flow into an error path.
+
+---
+
+## Phase 1 — Assess (shared stage)
+
+Load [[flow.recipes.testing.shared-stages.intent-analyzer]].
+
+It confirms the flow is **save-eligible** (`"FlowTesting"` in the
+features list — narrower than debug eligibility), reads the flow shape,
+and emits the assessment object the builder consumes. Silo mode is
+auto-detected the same way as in author-test; if the user named an
+`@testSetup` class, the silo gate (`"FlowTestingWithDataSilo"`) is
+probed too.
+
+If the flow is not save-eligible, STOP and route to
+[[flow.recipes.testing.workflows.debug]] for ad-hoc validation — there
+is no persistent artifact to produce. Do not call
+`POST /services/data/vXX.0/flowbuilder/flow-test` / `PATCH /services/data/vXX.0/flowbuilder/flow-test/{id}` against an ineligible flow.
+
+---
+
+## Phase 2 — Build (shared stage, assertions skipped)
+
+Load [[flow.recipes.testing.shared-stages.payload-builder]]. Run it
+**without Step 4**:
+
+- **Step 2** — top-level fields. `doesCommitChanges: false` unless the
+  user explicitly asked for a committing test. If the Intent Analyzer's
+  `flowShape.hasWaits` is `true`, also decide `doesTestWaitElement`:
+  a `WithoutAssertion` test is a saved debug-run setup, and
+  `doesTestWaitElement: true` makes it pause at Waits when replayed, as the
+  debug run did. Propose `true` when the flow is an autolaunched flow with
+  no trigger.
+- **Step 3** — the Start `testPoint`, bound by trigger type per
+  [[flow.recipes.testing.flowtest-elements.parameters]]. This is the
+  whole payload's substance — pin the real inputs the scenario uses
+  (a real record ID for record-triggered, one `InputVariable` per
+  declared variable for non-triggered).
+- **Skip Step 4 entirely.** No assertion `testPoint`. The single Start
+  entry carries `assertions: []`.
+- **Step 5** — `testType: "WithoutAssertion"`. (With no non-empty
+  `assertions[]` anywhere, this is the only correct value; the reviewer
+  auto-fix in Phase 3 confirms it.)
+- **Step 6** — silo additions only if `siloMode: true`.
+
+The result is a one-`testPoint` payload: `Start` bound, `assertions:
+[]`, `testType: "WithoutAssertion"`.
+
+---
+
+## Phase 3 — Review (shared stage, auto-fixes only)
+
+Load [[flow.recipes.testing.shared-stages.reviewer]], but only its
+**job 1** applies here:
+
+- **Apply the cheap local auto-fixes** — `testType` correctness,
+  `flowVersionNumber` stringification, `sobjectValue` stringification,
+  legacy `"Input"` → `"InputVariable"`. Report each as a one-line `WARN`.
+
+The reviewer's **job 2 (assertion intent check) does not apply** — there
+are no assertions to second-guess. The one intent concern that *does*
+survive is the same as promotion's: a `WithoutAssertion` test built from
+a throwaway `sobjectValue: "{}"` placeholder isn't a durable scenario.
+If the Start binding is `"{}"` rather than a real record, `BLOCK` and ask
+for a real record ID before saving.
+
+---
+
+## Phase 4 — Save & run
+
+**Invariant — no broken test lingers in the org without the user's
+say-so.** Same rule as author-test Phase 5: on terminal run failure,
+pause and ask the user how to handle the artifact. `save-debug`
+always starts with a `POST /services/data/vXX.0/flowbuilder/flow-test` (first-time save) and never has a prior passing
+state to restore to, so the cleanup choice is **delete-or-keep** —
+rollback doesn't apply here. The single carve-out is the fault-path
+case at the end of this phase — a `WithoutAssertion` test that
+consistently reaches a known fault is a valid regression scenario,
+so the failure IS the intended artifact and the cleanup prompt is
+skipped (confirm this intent with the user before treating the
+failure as intended).
+
+`POST /services/data/vXX.0/flowbuilder/flow-test` with body `flowTestJson`. Continue only when
+`isSuccess === true` and `flowTestId` is a non-empty string; capture that
+`320xxx` ID.
+
+On `isSuccess: false`, surface each returned error's `message` and
+`statusCode`; target a field only if the message identifies one, then
+re-save (cap: one retry). The server's deep validator owns structural
+correctness — don't pre-check against a memorized rule list. **No org
+cleanup needed** on a failed `POST /services/data/vXX.0/flowbuilder/flow-test` — nothing was persisted.
+If status or a usable ID is missing, surface the raw response and stop;
+the create outcome is unproven, so do not run, update, or delete without a
+confirmed ID.
+
+Then **run it once** — `POST /services/data/vXX.0/flowbuilder/flow-test/actions/run` with the pinned `flowVersionId`
+(**required**), the new `testIds`, and `showTrace: true`. Read per
+[[flow.recipes.testing.run-results]]:
+
+- `testStatus: "Pass"` → success for the documented run-result contract.
+  Report the `320xxx` ID and the version it's pinned to, and surface any
+  `interviewErrors` or `lastRunError` fields that are also present.
+- Missing/empty `results` or a server error with no descriptor → no
+  documented per-test descriptor is available. Surface the raw response without inferring a
+  cause. Round-trip via `GET /services/data/vXX.0/flowbuilder/flow-test/{id}`, parse `flowTestJson`, and compare
+  it with what was sent. Apply one fix only if that comparison proves a
+  discrepancy, then call `dispatch(method: "PATCH", url: "/services/data/vXX.0/flowbuilder/flow-test/{id}")` with
+  `{id, flowTestJson: JSON.stringify(completeDefinition)}`. Re-run only
+  when the update returns `isSuccess === true`; otherwise surface its
+  errors or raw response and hand off to terminal failure. If the second
+  run still fails, hand off to the Terminal failure section below.
+- Any returned descriptor whose `testStatus` is missing or is not exactly
+  `Pass` → report `lastRunFailedAssertions`, `lastRunError`, and
+  `interviewErrors` when present, then hand off to Terminal failure. Do not
+  assume a runtime error means `results` is absent.
+- A fault path the user actually wants to lock in → the fault-path
+  carve-out applies. Confirm with the user; if confirmed, keep the
+  test and skip the Terminal failure prompt.
+
+### Terminal failure — user chooses cleanup
+
+Reached when no descriptor reports exactly `testStatus: "Pass"` after the one-shot self-correct
+and the fault-path carve-out does not apply.
+
+1. **Surface the failure.** Report to the user:
+   - (a) the verbatim run signal — `testStatus`, `lastRunFailedAssertions`,
+     `lastRunError`, `interviewErrors`, the retrieved-vs-sent diff, or the
+     raw absent/empty `results` response;
+   - (b) the specific binding field(s) implicated only when the response
+     identifies them;
+   - (c) the current org state — the `320xxx` id.
+
+2. **Ask the user how to handle the artifact:**
+
+   > This smoke test is broken as saved. How do you want to handle it?
+   > - **delete** — remove the `320xxx` from the org.
+   > - **keep** — leave it in place for hand-editing; I'll report the
+   >   `320xxx` and the failure trace.
+
+   Silence is not consent — wait for a reply.
+
+3. **Execute the choice:**
+   - **delete** → `DELETE /services/data/vXX.0/flowbuilder/flow-test/{id}` with the CURRENT
+     smoke test's `320xxx` as the path `id` (single id per call —
+     there is no bulk delete). `save-debug` is one-shot per
+     invocation, so there is never more than one id in scope here.
+     Report deletion only when `isSuccess === true`. On `false`, surface
+     `errorMessage` when present; when status is missing, report the delete
+     outcome as unproven. The parent flow is untouched.
+   - **keep** → leave the artifact in place; report the `320xxx`, the
+     failure trace, and the pointer to `DELETE /services/data/vXX.0/flowbuilder/flow-test/{id}`
+     for later cleanup if the user changes their mind.
+
+4. **Offer a redesign.** After cleanup, ask whether to re-enter at
+   Phase 1 (Assess) with a different binding, or stop.
+
+---
+
+## Editing an existing WithoutAssertion test
+
+To change the pinned inputs, parse the current complete definition, make
+the edits, and call `dispatch(method: "PATCH", url: "/services/data/vXX.0/flowbuilder/flow-test/{id}")` with
+`{id, flowTestJson: JSON.stringify(completeDefinition)}`. Require
+`isSuccess === true`; the wire shape has no partial patch. To **add**
+assertions later (promote a smoke test to a real
+assertion test), switch to
+[[flow.recipes.testing.workflows.author-test]]'s build phase: add a
+`Finish` `testPoint`, flip `testType` to `"WithAssertion"`, and re-save.
+
+---
+
+## Notes for callers
+
+- This recipe is intentionally thin: it is author-test minus assertion
+  authoring and minus the assertion-intent review. If a scenario grows an
+  expectation, it graduates to author-test — don't bolt assertion logic
+  onto this path.
+- Tool budget: 2–4 calls in the happy path (1 retrieve for eligibility/
+  shape via the analyzer, 1 store, 1 run, optionally 1 retrieve
+  round-trip on failure).

package/skills/automation-flow-coordinate/references/resources/variable/variable.md

@@ -0,0 +1,171 @@
+---
+name: flow-resource-variable
+license: LICENSE.txt has complete terms
+description: "Use this skill when creating, editing, or asking about Flow variables, including collection variables, variable data types, input/output availability, default values, and the isExternallyAccessible setting. TRIGGER when: user asks to create a variable, declare a collection, set input/output availability, or configure variable data types. DO NOT TRIGGER when the user needs a formula or constant (use flow-resource-formula or flow-resource-constant)."
+metadata:
+  version: "1.0"
+  related-skills: flow-value-rules, flow-formula-expression, flow-resource-constant
+---
+
+# Flow Variables
+
+## Reference File Index
+
+| File | Purpose |
+|---|---|
+| `examples/sobject-collection.json` | SObject collection variable |
+| `examples/apex-collection.json` | Apex collection variable with output |
+| `examples/currency-with-default.json` | Currency variable with default value |
+| `examples/number-counter.json` | Number counter variable |
+| `examples/wrong-both-types.json` | WRONG: Both objectType and apexClass set |
+| `examples/wrong-collection-default.json` | WRONG: Collection with default value |
+| `examples/wrong-currency-scale-zero.json` | WRONG: Currency with scale=0 |
+| `examples/wrong-scale-exceeds-limit.json` | WRONG: Scale exceeds maximum of 17 |
+| `examples/wrong-missing-scale.json` | WRONG: Missing required scale field |
+
+## Overview
+A variable is a named container that holds a value during a flow's execution. Variables can hold a single value or a collection (list) of values. They can be passed in from outside the flow (input), passed back out when the flow finishes (output), or used purely inside the flow.
+
+## When to Use
+Use a variable when you need to store, modify, or pass data within a flow. Use a collection variable when you need to work with multiple records or values of the same type. Use input/output settings to share data between flows or with calling code.
+
+## Required Properties
+| Property | Description | Constraints |
+|---|---|---|
+| Name (API Name) | Developer-facing unique identifier | Max 80 characters; must follow API naming rules |
+| Data Type | The type of data the variable holds | Must be one of the supported types listed below; cannot be changed after creation |
+
+## Optional Properties
+| Property | Description | Default |
+|---|---|---|
+| Description | Human-readable explanation of the variable's purpose | Empty string |
+| Collection | Whether the variable holds multiple values of the same type | false |
+| Default Value | The initial value assigned to the variable | null (none) |
+| Scale | Decimal places for Number and Currency types (range: 0-17) | Metadata default when omitted: 0; recommended for Currency: 2 (see Key Rules) |
+| Object Type (subtype) | The Salesforce object or Apex class when Data Type is Record or Apex | null |
+| Available for Input | Lets external callers pass a value in when the flow starts | false |
+| Available for Output | Exposes the variable's value to callers after the flow runs | false |
+| Externally Accessible | Controls whether the variable is exposed at all in capability-triggered flows | Depends on flow trigger type (true for most flows; false for automatic-input capability-triggered flows) |
+
+## Data Types Supported
+All of the following data types are supported for variables:
+
+- **String** — text values
+- **Number** — numeric values; supports a decimal scale
+- **Currency** — monetary values; supports a decimal scale
+- **Boolean** — true/false
+- **Date** — a calendar date
+- **DateTime** — date plus time
+- **Time** — time of day (only available when the org has Time data type support and the flow process/trigger type supports it)
+- **Picklist** — a single picklist value (no default value allowed)
+- **Multi-Select Picklist** — multiple picklist values (no default value allowed)
+- **Record (SObject)** — a Salesforce object record; requires selecting the Object Type; no default value allowed
+- **Apex** — an Apex-defined type; requires selecting the Apex Class; the Apex class must be global or accessible from Flow context; no default value allowed; supports field access via dot-notation (e.g., `varWrapper.fieldName`)
+
+## Collection Variables
+Any data type can be used as a collection variable by checking "Allow multiple values (collection)". Key constraints:
+- Collection variables **cannot have a default value**, regardless of data type.
+- Collection variables with Record or Apex types behave like lists of records/objects.
+- When `isCollection` is true, the `defaultValue` field is always ignored.
+
+## Default Value Constraints
+Default values are only available for these types on **non-collection** variables:
+- String, Number, Currency, Boolean, Date, DateTime, Time
+
+Default values are **NOT** available for:
+- Picklist
+- Multi-Select Picklist
+- Record (SObject)
+- Apex
+- Any collection variable
+
+The default value can be a literal or a reference to another resource (a value object).
+
+## Input / Output Availability
+- **Available for Input (isInput)** — the variable can be populated from the outside when the flow is invoked. Changing this setting on an existing variable that is already used as an input may cause runtime errors in calling flows.
+- **Available for Output (isOutput)** — the variable's value is returned to the caller after the flow ends. Changing this or renaming an output variable on an existing flow may break calling flows.
+- A warning is shown in the editor when you rename a variable or change its input/output settings if it was previously marked as input or output.
+- Both can be true simultaneously (the variable is both readable and writable from outside the flow).
+
+## isExternallyAccessible
+- Controls whether the variable appears at all in external access contexts.
+- Defaults to `true` for most flow types.
+- Defaults to `false` specifically for capability-triggered flows that use automatic (non-manual) input configuration. In that case the variable is hidden from external callers unless the org has `optionalCapabilities` enabled and the flow is set to manual input.
+- This is separate from `isInput`/`isOutput` — `isExternallyAccessible` gates visibility; `isInput`/`isOutput` control the direction.
+
+## Validation Rules & Constraints
+- Data Type must be set (cannot be null or undefined).
+- When Data Type is Record (SObject) or Apex, the subtype (Object Type or Apex Class) is also required.
+- Default value, if provided, must pass the resource-picker validation for the variable's data type.
+- The data type **cannot be changed** after a variable has been saved (editor disables the picker in edit mode).
+- API name max length is 80 characters. A variable has no label, only its API name: a `<label>` in `<variables>` fails the save.
+
+## Common Patterns
+- Store a record retrieved via Get Records into a Record variable to reuse its field values later.
+- Use a collection Record variable as the target when Get Records returns multiple records.
+- Mark a String variable as both input and output to pass data in, process it, and return the result.
+- For scale guidance on Number/Currency variables, see the `scale` rule in the Metadata Shape > Key rules section.
+- A Boolean variable is useful as a flag to track whether a condition was ever met during the flow.
+- Use Apex collection variables as Transform element outputs when mapping SObject records to custom wrapper classes.
+
+## Aura/Server Functions
+- `getFlowInputOutputVariables` — retrieves the input and output variable definitions for a referenced flow (used when configuring subflow variable assignments)
+
+## Metadata Shape
+
+Variables live in `metadata.variables[]`. Each entry:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | yes | dev-name; unique within the flow; ≤ 80 chars; ASCII alphanumeric + underscore |
+| `description` | string | no | empty string by default |
+| `dataType` | string | yes | `String`, `Number`, `Currency`, `Date`, `DateTime`, `Boolean`, `Picklist`, `Multipicklist`, `SObject`, `Apex` |
+| `isCollection` | boolean | no | default `false` |
+| `isInput` | boolean | no | default `false` — "Available for input" |
+| `isOutput` | boolean | no | default `false` — "Available for output" |
+| `scale` | number | **required** for `Number`/`Currency` | decimal places (0-17); **must not be null** — default to `0` if unspecified |
+| `objectType` | string | conditional | ONLY when `dataType` = `"SObject"` |
+| `apexClass` | string | conditional | ONLY when `dataType` = `"Apex"` |
+| `value` | value object | no | optional default value |
+
+### Key rules
+
+- `dataType` must use exact Metadata API casing. Note: Multi-Select Picklist is `"Multipicklist"` (capital M, lowercase p) — NOT `"MultiPicklist"` or `"MultiSelectPicklist"`, which are rejected with a deserialization error.
+- `objectType` is set if and only if `dataType === "SObject"`. `apexClass` is set if and only if `dataType === "Apex"`. **Never set both** — they are mutually exclusive.
+- `scale` is required for `Number` and `Currency` (range: 0-17) — omitting it (null) causes a save warning that blocks activation. **Always set scale explicitly:** use `scale: 2` for Currency (standard financial precision), `scale: 0` for Number counters/IDs, `scale: 4-6` for scientific calculations. If the caller hasn't specified precision, default to `0` as a technical fallback, but note that `scale: 0` is rarely appropriate for Currency types as it truncates fractional amounts.
+- `value` (default) is a value object (see `../../shared/value-rules.md` for complete value object rules). Omit the `value` field entirely when there is no default. Collection variables and SObject/Apex/Picklist variables cannot have a default value.
+- `isCollection: true` is required when the variable will hold multiple rows (e.g. output of a `recordLookup` without `getFirstRecordOnly`, or an accumulator inside a `Loop`). An Assignment with `operator: "Add"` requires the target variable to be a collection OR a Number/Currency (for increment operations).
+- `isInput: true` / `isOutput: true` variables define this flow's subflow contract. A calling flow's `inputAssignments[].name` must match an `isInput: true` variable in the called flow.
+- When using Apex variables, verify the Apex class exists in the org before declaring the variable. The class must be global or accessible from the Flow context.
+- Access fields on SObject or Apex variables using dot-notation: `varAccount.Name` or `varWrapper.orderNumber`.
+- Declare only the variables that other elements reference. Speculative declarations bloat the flow and cause confusion.
+- Variables don't have connectors and cannot throw.
+
+### Save-time rejections
+
+- `Variable '<name>' has both objectType and apexClass`
+- `objectType '<name>' is not a valid sObject`
+- `Variable '<name>' dataType requires objectType` (SObject without `objectType`)
+- `In field: apexClass - no ApexClass named '<name>' found` (Apex variable with invalid class)
+- `Variable '<name>' value type mismatch with dataType`
+- `Can not construct instance of ...FlowDataType from String value 'MultiPicklist'` (wrong casing; use `Multipicklist`)
+- `Cannot use Add operator on a non-collection variable` (Note: Add works on Number/Currency for increment operations)
+- `Variable '<name>' has scale exceeding limit of 17` (scale > 17)
+- `Element {http://soap.sforce.com/2006/04/metadata}label invalid at this location in type FlowVariable` (a `<label>` in a variable; remove it)
+
+## Common Errors
+
+**Both objectType and apexClass set**
+See `examples/wrong-both-types.json`. Error: `Variable 'invalidVariable' has both objectType and apexClass`. These fields are mutually exclusive.
+
+**Collection with default value**
+See `examples/wrong-collection-default.json`. The `value` field is ignored; collections cannot have defaults and will be uninitialized.
+
+**Currency with scale=0**
+See `examples/wrong-currency-scale-zero.json`. While technically valid, `scale: 0` truncates fractional monetary amounts (e.g., $10.50 becomes $10). Always use `scale: 2` for standard financial precision unless you specifically need whole-dollar amounts.
+
+**Scale exceeds limit**
+See `examples/wrong-scale-exceeds-limit.json`. Error: `Variable 'preciseNumber' has scale exceeding limit of 17`. Maximum scale is 17.
+
+**Missing scale for Currency/Number**
+See `examples/wrong-missing-scale.json`. Activation blocked until `scale` is set. Default to `scale: 0` if unspecified.