@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/automation-flow-coordinate/references/elements/start/data-cloud-data-change-triggered.md

@@ -0,0 +1,92 @@
+---
+name: flow-element-start-data-cloud-data-change-triggered
+license: LICENSE.txt has complete terms
+description: "Load when building a Data Cloud-Triggered flow — triggerType `DataCloudDataChange`, processType `AutoLaunchedFlow` — that FIRES when a single Data Cloud DMO record is created or updated. Covers discovering the DMO at runtime (`flowbuilder_get_data_cloud_entities` + entity fields), the start-element shape (`object` = DMO API name, `recordTriggerType`), referencing the changed record via `$Record.<dmoField>` in a downstream Decision, the rule that Create/Update/Delete elements must target a writable SObject (never a DMO), and the hard line vs a data-graph trigger (`DataGraphDataChange`), vs core-SObject record triggers (`RecordAfterSave`/`RecordBeforeSave`/`RecordBeforeDelete`), vs an engagement `AutomationEvent`. DO NOT load for any other trigger type."
+metadata:
+  version: "1.0"
+  related-skills: flow-element-start, flow-flow-properties
+---
+
+# Data Cloud-Triggered (Single DMO Record Change)
+
+Load this when `triggerType` is `DataCloudDataChange`. It is the complete build guide for the Data Cloud-triggered start element; the base `start.md` carries only the routing stub.
+
+The whole flow FIRES when a **single Data Cloud Data Model Object (DMO) record** is created or updated — the changed DMO record is exposed to the flow body as `$Record`. This is a record-change trigger on **one** DMO, not on a data graph (multiple related objects) and not on a core CRM SObject.
+
+- **triggerType**: `DataCloudDataChange`. Author **`processType: "AutoLaunchedFlow"`** (headless). Do not substitute a core record trigger based on the word "record" in the prompt.
+- The DMO is chosen ON the start element via **`object`** — set to the DMO's bare API name (a `ssot__*__dlm` / `*__dlm` developer name), the same field a core record trigger uses for its SObject.
+- Supports **`recordTriggerType`** `Create`, `CreateAndUpdate`, or `Update` — there is **no `Delete`** for this trigger (unlike a core `RecordBeforeDelete`).
+- Requires a **Data Cloud-provisioned org** and **API version 59.0+**: the `DataCloudDataChange` trigger and DMOs do not exist on a plain org. If the trigger type is not offered, or no DMO matches the user's intent, STOP and tell the user the org is not Data Cloud-provisioned — do NOT fall back to a core record trigger or an engagement event.
+
+## Discover the DMO — don't hard-code it
+
+The DMO name is org-specific; treat discovery as the source of truth. Do not guess a `ssot__*__dlm` name.
+
+1. **List the org's Data Cloud DMOs.** Call the salesforce-flow tool **`flowbuilder_get_data_cloud_entities`** to enumerate the Data Cloud DLM/DMO entities the org exposes (with their capabilities). Match the user's intent (the object whose change should fire the flow) to a row and take its **exact API name** (e.g. `ssot__Opportunity__dlm`). If nothing matches, STOP (see the provisioning note above) — do not substitute a core SObject.
+2. **Set the trigger identity from it.** Put that exact DMO API name in **`start.object`** and set **`recordTriggerType`** (`Create`, `CreateAndUpdate`, or `Update`) from the user's intent.
+3. **Learn the DMO's fields** for `$Record.<field>` references and any entry filters: `dispatch_readonly(method: "GET", url: "/flowbuilder/platform/entity/<the DMO API name>/fields")`. Reference only fields this returns — a field valid on a core SObject may not exist on the DMO.
+
+> **Capabilities probe won't list these fields.** The `DataCloudDataChange` start-field shape (`object` + `recordTriggerType` on a DMO) is not advertised by a flow-capabilities / metadata-describe probe — it only surfaces on validation. Build the start from this guide; do NOT conclude the trigger is unsupported just because a capabilities call doesn't enumerate it.
+
+## Do NOT confuse with three look-alikes
+
+| The user wants… | Use | Where / how the object is set |
+|---|---|---|
+| the flow to **FIRE when a single Data Cloud DMO record** is created/updated | **`DataCloudDataChange`** start (this guide) | `object` = the **DMO** API name (`ssot__*__dlm`) on the **start** |
+| the flow to fire on a **multi-object DATA GRAPH** change | **`DataGraphDataChange`** — NOT this guide (see "Out of scope" below); it is org-gated | `triggeringDataGraph` + `triggeringDataModelObjectPath` on the start |
+| the flow to fire on a **core CRM SObject** create/update/delete (Account, Opportunity, Contact, custom `__c`) | `RecordAfterSave` / `RecordBeforeSave` / `RecordBeforeDelete` — see `start.md` | `object` = the **SObject** API name (never a `__dlm` DMO) |
+| the flow to fire on an **email-engagement event** (open / link click / bounce / response) | `AutomationEvent` — see `automation-event-triggered.md` | `eventName` / `eventType` on the start |
+
+A DMO API name ends in `__dlm`; a core SObject does not. If the target ends in `__dlm`, this is `DataCloudDataChange` (single DMO) or `DataGraphDataChange` (a data graph) — never a core record trigger.
+
+## Start element shape
+
+| Field | Value |
+|---|---|
+| `triggerType` | `"DataCloudDataChange"` |
+| `object` | the triggering DMO's API name — from discovery (e.g. `"ssot__Opportunity__dlm"`) |
+| `recordTriggerType` | `"Create"`, `"CreateAndUpdate"`, or `"Update"` (no `Delete`) |
+| `filters` / `filterLogic` | optional entry criteria on the DMO's fields; omit `filterLogic` when `filters: []` (the no_conditions omission rule — see `start.md`) |
+| `doesRequireRecordChangedToMeetCriteria` | optional; only valid for `Update` / `CreateAndUpdate` |
+| `processType` (flow root) | `"AutoLaunchedFlow"` |
+
+```json
+"start": {
+  "locationX": 0, "locationY": 0,
+  "triggerType": "DataCloudDataChange",
+  "object": "ssot__Opportunity__dlm",
+  "recordTriggerType": "Create",
+  "filters": [],
+  "doesRequireRecordChangedToMeetCriteria": false,
+  "connector": { "targetReference": "<first element>", "isGoTo": false }
+}
+```
+
+*Note: the DMO name above is illustrative — use the exact API name `flowbuilder_get_data_cloud_entities` returns for the org.* A verified reference build saved AND validated cleanly (no `InvalidDraft`) with just `object` + `recordTriggerType` + empty `filters`; no flow-level `dataSpace` was required to save or validate this single-DMO trigger.
+
+Do **NOT** emit `triggeringDataGraph` or `triggeringDataModelObjectPath` on a `DataCloudDataChange` start — those fields belong to `DataGraphDataChange` only (see "Out of scope").
+
+## `$Record` — the triggering DMO record
+
+- `$Record` = the changed DMO record; it is **read-only**.
+- Reference the changed record's fields as **`$Record.<dmoField>`** (e.g. `$Record.ssot__TotalAmount__c`) — use only field API names returned by the entity-fields describe in discovery.
+- The "decide on the triggering record's data" pattern is a body **Decision** whose conditions read `$Record.<dmoField>`. Do the criteria evaluation in the body; the start's optional entry `filters[]` narrow which DMO changes enter the flow at all (literal typed values only, same restrictions as a record-triggered start — see `start.md` / [[flow.shared.record-filter]]).
+
+## Write targets — DMOs are read/trigger-only
+
+Data Cloud DMOs are **read/trigger-only**: their fields are not creatable, and a DMO is never a valid write target. A `Create Records` / `Update Records` / `Delete Records` element in this flow MUST target a normal **writable SObject** (e.g. `Task`, `Case`, a custom `__c`), never a `__dlm` DMO.
+
+Canonical pattern for this flow type:
+
+> DMO record change (`DataCloudDataChange` start) → read `$Record.<dmoField>` → Decision on criteria → **Create Records on a writable CRM SObject** (e.g. a `Task`) populated from `$Record` fields.
+
+## Special treatment — what discovery does NOT tell you
+
+- **Version floor (functional prerequisite):** `DataCloudDataChange` requires **API version 59.0+**. Below that floor the trigger is unavailable — check the flow's API version.
+- **No `Delete`:** `recordTriggerType` is `Create` / `CreateAndUpdate` / `Update` only. There is no before/after-delete flavor for this trigger.
+- **No data-graph fields:** `triggeringDataGraph` / `triggeringDataModelObjectPath` are `DataGraphDataChange`-only — emitting them here is wrong.
+- **`dataSpace` is not required to save/validate** the single-DMO trigger (unlike Segment / Automation Event flows). If a specific target org blocks **activation** with `DATA_SPACE_REQUIRED_FOR_FLOW_TYPE`, resolve a data space via `d360_dataspace_list` (H360 `dispatch` — see `audience-common.md`) and set it as the flow-level `dataSpace`; otherwise omit it.
+
+## Out of scope — data-graph trigger (STOP and route)
+
+`DataGraphDataChange` (fire on a change across a **multi-object data graph**) is a DIFFERENT trigger type, not this single-DMO one. It is **org-gated**: it needs Real-Time Data Graphs enabled on the org, the create/modify-data-graph-trigger user permission, and API version 63.0+, and its start uses `triggeringDataGraph` + `triggeringDataModelObjectPath` (its primary DMO must be `UnifiedIndividual` / `Individual`). If the user wants a data-graph-scoped trigger, that is a separate capability — do NOT emit `DataGraphDataChange` fields on a `DataCloudDataChange` flow, and do NOT silently downgrade a data-graph request to a single-DMO trigger. Confirm the org is provisioned for it first.

package/skills/automation-flow-coordinate/references/elements/start/form-submission-triggered.md

@@ -0,0 +1,88 @@
+---
+name: flow-element-start-form-submission-triggered
+license: LICENSE.txt has complete terms
+description: "Load when building a Form-Triggered flow — triggerType `FormSubmissionEvent`, processType `AutoLaunchedFlow` — that FIRES each time someone submits a Marketing form (a Form Builder form stored as Managed Content, `sfdc_cms__form`). Covers discovering the form at runtime (ManagedContent SOQL + the content-FQN endpoint), the start-element shape (`form` = the form's content FQN), reading the submitted answers via `$Form.<field>`, the one-form-per-flow rule, and the HARD PROHIBITION on authoring it as `AutomationEvent` + `trgrOnFormSubmission` (Flow Builder lists Form Submission under Automation Event, but the saved trigger type is `FormSubmissionEvent`). Also the line vs a Screen flow (a form the user steps through). DO NOT load for any other trigger type."
+metadata:
+  version: "1.0"
+  related-skills: flow-element-start, flow-flow-properties
+---
+
+# Form-Triggered (Marketing Form Submission)
+
+Load this when `triggerType` is `FormSubmissionEvent`. It is the complete build guide for the form-submission start element; the base `start.md` carries only the routing stub.
+
+The whole flow FIRES, headless, once per submission of a Marketing form. The submitted answers are available in the flow body as `$Form.<field>`.
+
+- **triggerType**: `FormSubmissionEvent`. Author **`processType: "AutoLaunchedFlow"`**.
+- The form is chosen ON the start via the **`form`** field — the form's Managed Content FQN. There is no `eventName`/`eventType` and no start `inputs[]` on this trigger.
+- Requires a Marketing-provisioned org with at least one Form Builder form. If the trigger type is unavailable or the org has no form, STOP and tell the user — do NOT fall back to another trigger type, and never fabricate a form value.
+
+## HARD PROHIBITION — never `AutomationEvent` + `trgrOnFormSubmission`
+
+Flow Builder lists **Form Submission** inside the **Automation Event** trigger picker, and event discovery scoped to the Automation Event trigger (`GET /services/data/vXX.0/flowbuilder/action/invocable-events` with `triggerType: "AutomationEvent"`) returns a `trgrOnFormSubmission` row labeled "Form Submission". **Do not build on that row.** When a user picks Form Submission in the builder, the builder rewrites the flow to `triggerType: FormSubmissionEvent`; it never saves `AutomationEvent` + `trgrOnFormSubmission`.
+
+If you author that shape anyway, the platform rejects it:
+
+- The event name is invalid (`FLOW_INVALID_EVENT_NAME`, "Invalid event name trgrOnFormSubmission."); on save the server rewrites `eventName` to `"nullNotFound"`.
+- The flow saves as **`InvalidDraft`** (cannot be activated).
+- `$Form.<field>` references stop resolving (the start is no longer bound to a form).
+- The event's describe marks a `Form` input as required, but the validator then rejects that input (`FLOW_START_INPUT_INVALID_INPUT`, "Flows with event type Form Submission don't support the Form field"). The describe for this event is not a reliable guide — use this file instead.
+
+So: a form-submission request is ALWAYS `triggerType: FormSubmissionEvent`, even when the user says "Automation Event" or names the Form Submission event. When they used Automation Event wording, tell them in one line why the saved trigger type is `FormSubmissionEvent`.
+
+## Do NOT confuse with two look-alikes
+
+**Choosing between these is a flow-type classification decision — owned by the
+flow-type-resolver reference (`../../shared/flow-type-resolver/flow-type-resolver.md`).** Resolve there, not here. Once the type is resolved, this is where the trigger is set for each:
+
+| Request | Type | Where it is set |
+|---|---|---|
+| The flow runs AFTER someone submits an existing Marketing form (this guide) | `FormSubmissionEvent` | `form` on the **start** |
+| The flow IS the form — a user steps through screens and enters values | Screen Flow (`processType: Flow`, no trigger) | `screens[]` in the flow body |
+| The flow fires on an email engagement (open / link click / bounce / response) | `AutomationEvent` — see `automation-event-triggered.md` | `eventName`/`eventType` on the **start** |
+
+A plain record trigger on the object the form writes to (e.g. `RecordAfterSave` on `Lead` create) is also not a substitute: use `FormSubmissionEvent` when the user describes the form submission itself as the starting event.
+
+## Discover the form — don't guess it
+
+1. **List the org's forms.** `dispatch_readonly({ url: "/services/data/vXX.0/query", method: "GET", queryParams: { q: "SELECT Id, Name, ContentKey, AuthoredManagedContentSpaceId FROM ManagedContent WHERE ContentTypeFullyQualifiedName = 'sfdc_cms__form'" } })` → `records[]`, each `{Id (20Y…), Name, ContentKey, AuthoredManagedContentSpaceId}`. Match the form the user named against `Name`; select one exact match automatically, ask the user to choose when several match or the request does not identify one, and STOP when none exist (the user must create the form in Form Builder first).
+2. **Resolve its FQN.** `dispatch_readonly({ url: "/services/data/vXX.0/flowbuilder/messaging/content-fqn", method: "GET", queryParams: { managedContentId: "<the 20Y… Id>" } })` → `{ contentFqn, managedContentId }`. Bind the returned `contentFqn` to `start.form`. It has the shape `marketing--<ContentSpaceApiName>.sfdc_cms__form--<ContentKey>` (e.g. `marketing--Default_Content_Workspace.sfdc_cms__form--<CONTENT_KEY>`). Never hand-assemble it, and never bind the bare `ContentKey`, the `20Y…` Id, or the form title.
+3. **Read the form's field names.** `dispatch_readonly({ url: "/services/data/vXX.0/connect/cms/contents/<the 20Y… Id>", method: "GET" })` → `contentBody`. Each form input in the block tree carries `sfdc_cms:formInputNameProperty` (e.g. `Email`, `FirstName`, `Company`) — that value is the field you reference as `$Form.<name>`. The input's `sfdc_cms:fieldReference` shows which object field the form maps it to (e.g. `{!<provider>.Email}` on `Lead`). Reference only names that exist in the form.
+
+## Start element shape
+
+| Field | Value |
+|---|---|
+| `triggerType` | `"FormSubmissionEvent"` |
+| `form` | the `contentFqn` from discovery step 2 |
+| `eventName` / `eventType` / `inputs[]` | omit — this trigger has none (`actionName`/`actionType` are cleared on save) |
+| `processType` (flow root) | `"AutoLaunchedFlow"` |
+| `dataSpace` (flow root) | a Data Space developer name that resolves on the org (commonly `"default"`). Active form flows carry it; set it on the first save. |
+
+```json
+{
+  "processType": "AutoLaunchedFlow",
+  "dataSpace": "default",
+  "start": {
+    "locationX": 0, "locationY": 0,
+    "triggerType": "FormSubmissionEvent",
+    "form": "marketing--Default_Content_Workspace.sfdc_cms__form--<CONTENT_KEY>",
+    "connector": { "targetReference": "<first element>", "isGoTo": false }
+  }
+}
+```
+
+See `examples/formSubmission.json` for a start plus a Create Records element that maps the submitted answers.
+
+## Read the submitted answers — `$Form.<field>`
+
+- Reference each answer as **`$Form.<formInputNameProperty>`** (e.g. `elementReference: "$Form.Email"`) in assignments, decisions, and record create/update input assignments.
+- Do NOT use `$Event.<field>` or `$Record` — neither carries the submission.
+- A system-variable listing may not show `$Form`; the validator still resolves it against the bound form. A name the form does not contain fails with "The "<Name>" field doesn't exist in your form content. Use an existing field or add the field to the form in Form Builder." — fix the name from discovery step 3; do not invent fields.
+
+## Save-time rules
+
+- **One form, one flow.** A form can drive only one flow. Binding a form that another flow (or another draft version) already uses is an unsaveable error (`FORM_ALREADY_IN_USE_BY_FLOW` / `FORM_ALREADY_IN_USE_BY_DRAFT_VERSION`). If you hit it, STOP and tell the user which form is taken; do not silently switch to a different form.
+- **The form must exist.** A `form` value that does not resolve to Managed Content is an unsaveable error (`FORM_CONTENT_NOT_FOUND`). This is why discovery step 2 is mandatory.
+- **A draft form is enough to save.** The form does not have to be published for the flow to save as `Draft`; check with the user before activating against an unpublished form.
+- **No fault paths unless asked.** A form-submission flow is a marketing flow: add a `faultConnector` or error-handling branch only when the user asks for error handling. See `../../shared/fault-paths/fault-paths.md` § Marketing Flows — Fault Paths Only When Asked.

package/skills/automation-flow-coordinate/references/elements/start/segment-triggered.md

@@ -0,0 +1,152 @@
+---
+name: flow-element-start-segment-triggered
+license: LICENSE.txt has complete terms
+description: "Load when building a Segment-triggered (Audience) marketing flow — triggerType `Segment`, processType `AutoLaunchedFlow`. Covers only what is Segment-specific: the segment name→ID→DMO binding chain (via `dispatch`-invoked Data 360 tools), the `segmentOnApiName` eligibility gate, `publishSegment`, segment outreach actions (BEA / send-to-journey), and the `$Record` member context. MUST load `audience-common.md` first for the shared run schedule / top-level `timeZoneSidKey` / `dataSpace` / `dataGraph` / re-entry contract. DO NOT load for any other trigger type."
+metadata:
+  version: "1.0"
+  related-skills: flow-element-start, flow-element-start-audience-common, flow-flow-properties
+---
+
+# Segment-Triggered (Audience Flow)
+
+Load this when `triggerType` is `Segment`. A broadcast flow that fans out a dynamic segment is `BroadcastNoTrigger`, documented in `start.md`. Do not load this file for it, and do not apply the eligibility gate below.
+
+> **MUST load [`audience-common.md`](audience-common.md) first.** It holds the
+> shared scheduled-audience contract — run schedule, top-level `timeZoneSidKey`,
+> top-level `dataSpace`, optional `dataGraph`, re-entry (`entryType`), the
+> save-and-activate gates, and the builder round-trip defaults, all identical
+> across `Segment`, `List`, `CampaignMember`, and `RecordQuery`. This file adds
+> ONLY what is specific to the Segment trigger: the segment binding, the
+> eligibility gate, `publishSegment`, outreach actions, and the `$Record` member context.
+
+- **triggerType**: `Segment`. Author `processType: "AutoLaunchedFlow"` for both
+  `POST /services/data/vXX.0/flowbuilder/flow/actions/save` and legacy `saveAndValidateFlow` lifecycles. This is the verified
+  Tooling API input and persisted value. Do not substitute `Journey` based on
+  the builder surface name or the live Connect enum member.
+- Targets a marketing segment/audience for outreach (email campaigns, drip sequences, re-engagement, nurture journeys).
+- Do NOT use `Scheduled` or `RecordAfterSave` for segment-based marketing — those lack audience targeting, segment membership context, and marketing frequency caps. A broadcast that fans out a dynamic segment now is `BroadcastNoTrigger`, not `Segment`.
+- For a `sendSmsMessage` flow, `dataGraph`, `schedule.frequency: "OnActivate"`,
+  and an explicit End node were observed in one hand-built draft's persisted
+  metadata. Preserve them when reproducing that flow, but do not treat them as
+  activation requirements without live validation evidence.
+
+## Reference File Index
+
+| File | Purpose |
+|---|---|
+| `audience-common.md` | The shared schedule / timezone / dataSpace / dataGraph / entryType contract (load first) |
+| `examples/segment-weekly-schedule.json` | Weekly run-schedule start-element example (the schedule shape is documented in `audience-common.md`) |
+
+## Bind the segment
+
+The prompt gives a segment name. `start.segment` and `start.object` are NOT
+derivable from it, and **plain SOQL cannot supply `segmentOnApiName`** — the
+`MarketSegment` sObject exposes `Id`, `Name`, `SegmentStatus`, `PublishStatus`,
+`SegmentMembershipTable`, `DataSpaceId`, and `DataGraphId`, but **not** the
+`segmentOnApiName` DMO that binds to `start.object`. Resolve the segment via the
+`dispatch`-invoked Data 360 (`d360_*`) segment tools before every save.
+
+The `d360_*` tools run through `dispatch`, not a standalone server: dispatch
+a POST to `/services/data/vXX.0/ssot/mcp/execute` with body
+`{ "toolName": "<d360_tool>", "paramsJson": "<params as a JSON-ENCODED STRING>" }`
+— `paramsJson` is a **string** (double-encoded JSON), never a nested object. Use
+`dispatch` (POST). If a tool's exact param shape is unclear,
+`discover` then `describe` the matching `d360_*` recipe before dispatching — don't
+guess the shape. (A `MarketSegment` SOQL query is fine as a supplemental
+name→`Id`/status lookup, but it can never stand in for the `d360` resolution
+because it lacks `segmentOnApiName`. Its `SegmentMembershipTable`, e.g.
+`Individual_Unified_SMH_<n>__dlm`, is the segment's membership table, never
+`start.object`: with it the org refuses to activate the flow ("The segment you
+selected in this flow's Start element contains objects that aren't associated
+with individuals").)
+
+1. `dispatch({ url: "/services/data/vXX.0/ssot/mcp/execute", method: "POST", body: { toolName: "d360_segment_get", paramsJson: "{\"segmentApiName\": \"<name>\"}" } })` — fast path only when the prompt supplies the segment's exact developer/API name.
+2. If that returns not-found (the prompt gave a display name, or a fuzzy/partial name), fall back to `d360_segment_list` (`paramsJson: "{\"batchSize\": 50, \"offset\": 0}"`), paginating with `offset` as needed, and match the target in `result.segments[]` by its `displayName` or `apiName`. The list result already contains the same fields as `d360_segment_get` — no follow-up `get` call is needed once you've matched a row. (`d360_segment_get_by_id`, `paramsJson: "{\"segmentId\": \"<1sg… id>\"}"`, resolves a segment already known by `marketSegmentId`.)
+   - **No segment in the org matches the prompt's name at all → STOP and ask the user for the correct segment name.** Do NOT silently substitute a different, unrelated segment that happens to exist (e.g. picking whatever segment comes back first) — a flow built against the wrong audience is worse than no flow.
+3. From whichever call resolved the segment, read:
+   - `marketSegmentId` (18-char `1sg…`) → `start.segment`.
+   - `segmentOnApiName` → `start.object`.
+   Require `segmentStatus: "ACTIVE"` and `publishStatus: "SUCCESS"` when the
+   response includes those fields. Stop when the segment is inactive,
+   unpublished, or its last publish failed.
+4. Eligibility gate — check `segmentOnApiName`:
+   - the Unified Individual DMO (e.g. `UnifiedIndividual__dlm`) → proceed; saves and activates cleanly.
+   - a non-unified Individual DMO (e.g. `ssot__Individual__dlm`) → proceed, but warn the user: the flow will SAVE, yet it can't ACTIVATE without an activation template (save returns a `WARNING_BLOCK_ACTIVATION` / `ACTIVATION_TEMPLATE_REQUIRED_FOR_NON_UNIFIED_INDIVIDUAL`; the template is set via `start.activationTemplate` — a dev name of an existing Data Cloud template — which this flow's save cannot create).
+   - anything else (`Account__dlm`, `Lead__dlm`, …) → STOP for a Segment-triggered flow. Tell the user the segment is built on `<segmentOnApiName>` and cannot trigger a segment flow; a segment on individuals is required. Do NOT substitute another segment. If the user asked for a broadcast flow, leave this file and author `BroadcastNoTrigger` instead of stopping.
+
+Set BOTH `segment` and `object` on every save; don't rely on a `segment` ID persisting on its own — re-set `object` from step 3 alongside it.
+
+Never write the segment name, `marketSegmentDefinitionId`, or `segmentOnId`
+into `start.segment`. Use `marketSegmentId`. An invalid value can return
+`isSuccess: true` with `InvalidDraft`, `FLOW_START_INPUT_INVALID_TYPE`, and an
+omitted persisted segment. Redo step 1/2 and save again.
+
+Salesforce record-ID substrings do not identify an org. Never compare fragments
+in unrelated record IDs to infer an authentication mismatch. Compare the
+Organization IDs returned by each authenticated service when org identity must
+be verified.
+
+On save error `TRIGGER_TYPE_CONTEXT_OBJECT_NOT_SUPPORTED` for a Segment-triggered flow: the segment is ineligible (individual-based required). Report it and do not retry with a substitute segment. This error does not apply to `BroadcastNoTrigger`.
+
+`object` is the `segmentOnApiName` DMO from step 3 (e.g. `"UnifiedIndividual__dlm"`), NOT anything from a data graph and NOT the `SegmentMembershipTable`.
+
+| Field | Value |
+|---|---|
+| `publishSegment` | Default `false`/omit: the flow does not (re)publish the segment; membership is assumed already published. Set `true` only if the prompt asks the flow to publish the segment when it runs. |
+
+## Record context — the segment member is `$Record`
+
+In a Segment flow, `$Record` is the current segment member: a row of the
+`segmentOnApiName` DMO (the `start.object`, e.g. `UnifiedIndividual__dlm`). Read
+the member's fields as **`$Record.<field API name>`**, for example
+`$Record.ssot__FirstName__c`. This works with or without a `dataGraph` on the Start
+element.
+
+**Always write the `$Record.` prefix.** A bare field name or a DMO-qualified name
+is rejected:
+
+| Reference | Result |
+|---|---|
+| `$Record.ssot__FirstName__c` | valid |
+| `ssot__FirstName__c` | `The "ssot__FirstName__c" element doesn't exist. Remove references to the element in all conditions.` |
+| `UnifiedIndividual__dlm.ssot__FirstName__c` | `The "UnifiedIndividual__dlm.ssot__FirstName__c" element doesn't exist. …` |
+
+Decision condition on the member's first name:
+
+```json
+{ "leftValueReference": "$Record.ssot__FirstName__c", "operator": "EqualTo", "rightValue": { "stringValue": "Alex" } }
+```
+
+Write the same reference in a condition-based exit rule's `conditions[]`
+(`../exit-rule/exit-rule.md`).
+
+Use field API names of the `segmentOnApiName` DMO; read them from the DMO's
+describe (`GET /services/data/vXX.0/flowbuilder/platform/entity/{apiName}/fields`)
+rather than guessing. Segment has **no `$Input` member row** (unlike
+List/CampaignMember/RecordQuery, see `list-campaignmember.md` / `recordquery.md`):
+do not invent one. `$Flow.*` globals remain available per the shared table in
+`audience-common.md`.
+
+## Data space note for `sendToJourney`
+
+The shared data-space rules live in `audience-common.md`. For `sendToJourney`
+specifically, also require the selected business unit's
+`businessUnitsToDataSpaces[].dataSpaceName` to equal the chosen data space `name`.
+Follow `../action-call/send-to-journey.md` for business-unit and Journey selection.
+
+## Data graph note for `sendSmsMessage`
+
+The shared data-graph rules live in `audience-common.md`. For `sendSmsMessage`,
+preserve a source flow's existing graph; do not select one solely to copy the
+observed example. A populated `dataGraph` was observed in the verified
+`sendSmsMessage` draft, but no save or activation error establishes it as mandatory.
+
+## Outreach actions for segment flows
+
+For flows that route segment members to a Buyer Engagement Agent (BEA) for email outreach, load `../forward-to-bot-or-agent/forward-to-bot-or-agent.md` and follow the **Outreach Initiation (BEA)** section.
+
+Key points:
+- The action is `forwardToBotOrAgent` with `modeSelector: "InitiateConversation"`. **Do NOT use `assignTargetToAgent`** — that action does not support the nudge count/interval/from-address parameters the BEA uses and is not the correct action for this flow type.
+- Set `areMetricsLoggedToDataCloud: true` at the `metadata` level (verified in BEA segment flow saves).
+- The flow ends with an explicit `ends[]` element; wire the action's `connector.targetReference` to it.
+- Schedule: `frequency: "OnActivate"` is the standard choice unless the user specifies a recurring cadence.