@salesforce/afv-skills 1.65.0 → 1.65.1

package/skills/health-cloud-timeline-configure/SKILL.md

@@ -1,622 +0,0 @@
----
-name: health-cloud-timeline-configure
-description: "Use this skill when users want to configure the Health Cloud Timeline feature: toggle the org-level Timeline preference (one-way enable; CannotTurnPrefOffError on disable), then create/update/activate/delete TimelineMetadataDefinition records binding an anchor entity to event-bearing related entities and optional. Trigger when users mention timeline."
-metadata:
-  version: "1.0"
-  accessCheck: "(Timeline.userCanAccessTimeline) || (Timeline.userCanConfigureCdpEventsOnTimeline)"
----
-
-# Managing Timeline
-
-## When to Use This Skill
-
-Configure the Health Cloud Timeline feature: toggle the org-level Timeline preference (one-way enable; CannotTurnPrefOffError on disable), then create/update/activate/delete TimelineMetadataDefinition records binding an anchor entity to event-bearing related entities and optionally Data Cloud DMOs. Anchor allowlist and Timeline-eligibility filters are server-enforced. All steps route through the timeline setup endpoint — AURA-IS-CANONICAL; no public Connect/Tooling/Metadata CRUD on TimelineMetadataDefinition exists (the /connect/timeline/* family is runtime read-only). Read flow: anchor → related-entities / parents / CRM objects → event / DMO details. Write flow: enable pref → save config (RecordId omitted=create, supplied=update) → activate via setActiveStatus. Config name + API name required on save.
-
-## Workflow
-
-Workflow: enable Timeline pref via handle-timeline-toggle (verify with get-timeline-org-pref) → list anchors via get-anchor-object → for the chosen anchor fan out via get-related-entities-of-anchor-entity / get-parent-objects-of-anchor-entity / get-related-crm-objects-of-anchor-entity (CDP path) → drill via get-event-object-details / get-related-entity-for-preview → read get-timeline-limits + get-timeline-cdp-limits to validate caps → call save-timeline-configuration with the assembled config (omit RecordId=create, supply=update) → set-timeline-configuration-active-status to activate. Use get-timeline-object-definitions(offset) for paged listing. Substitutions: none — every step is AURA-IS-CANONICAL; the /connect/timeline/* family is runtime read-by-name, not setup CRUD.
-
-## Critical Constraints
-
-**Preconditions:**
-
-- User must have Timeline AccessTimeline access (check: `Timeline access`)
-- User must have Timeline ConfigureCdpEventsOnTimeline access (check: `Configure Data Cloud events on timeline`)
-
-**Destructive operations — require explicit user confirmation:**
-
-- **`delete-timeline-configuration`** — Delete a saved Timeline definition by RecordId. Destructive — no soft-delete. AURA-IS-CANONICAL — no public CRUD alternative.
-  - Rollback: No automatic rollback.
-
-## Verification Checklist
-
-After every write operation, confirm the effect by re-reading state:
-
-- After `handle-timeline-toggle`: call `verify-handle-timeline-toggle` (`GET /headless/invoke/platform/timeline/get-timeline-org-pref`)
-- After `save-timeline-configuration`: call `verify-save-timeline-configuration` (`GET /headless/invoke/platform/timeline/get-timeline-object-definitions`)
-- After `delete-timeline-configuration`: call `verify-delete-timeline-configuration` (`GET /headless/invoke/platform/timeline/get-timeline-object-definitions`)
-- After `set-timeline-configuration-active-status`: call `verify-set-timeline-configuration-active-status` (`GET /headless/invoke/platform/timeline/get-timeline-object-definitions`)
-
-## Operations Reference
-
-Operations grouped by purpose. Use these as the building blocks for the workflows above.
-
-### Summary
-
-| Operation | Purpose | Status | Call | Depends on |
-|-----------|---------|--------|------|------------|
-| `is-data-space-enabled` | read | implemented | `GET /headless/invoke/platform/timeline` | — |
-| `get-data-spaces` | read | implemented | `GET /headless/invoke/platform/timeline/get-data-spaces` | — |
-| `get-timeline-org-pref` | read | proposed | `GET /headless/invoke/platform/timeline/get-timeline-org-pref` | — |
-| `get-timeline-data-cloud-events-enabled` | read | proposed | `GET /headless/invoke/platform/timeline/get-timeline-data-cloud-events-enabled` | `is-data-space-enabled` |
-| `get-timeline-data-graph-events-enabled` | read | proposed | `GET /headless/invoke/platform/timeline/get-timeline-data-graph-events-enabled` | `is-data-space-enabled` |
-| `handle-timeline-toggle` | write | proposed | `PATCH /headless/invoke/platform/timeline/handle-timeline-toggle` | — |
-| `verify-handle-timeline-toggle` | verify | — | `GET /headless/invoke/platform/timeline/get-timeline-org-pref` | `handle-timeline-toggle` |
-| `get-timeline-limits` | read | proposed | `GET /headless/invoke/platform/timeline/get-timeline-limits` | — |
-| `get-timeline-cdp-limits` | read | proposed | `GET /headless/invoke/platform/timeline/get-timeline-cdplimits` | — |
-| `get-anchor-object` | read | proposed | `GET /headless/invoke/platform/timeline/get-anchor-object` | — |
-| `get-timeline-object-definitions` | read | proposed | `GET /headless/invoke/platform/timeline/get-timeline-object-definitions` | — |
-| `save-timeline-configuration` | write | proposed | `PATCH /headless/invoke/platform/timeline/save-timeline-configuration` | `get-anchor-object` |
-| `verify-save-timeline-configuration` | verify | — | `GET /headless/invoke/platform/timeline/get-timeline-object-definitions` | `save-timeline-configuration` |
-| `set-timeline-configuration-active-status` | write | proposed | `PATCH /headless/invoke/platform/timeline/set-timeline-configuration-active-status` | `save-timeline-configuration` |
-| `delete-timeline-configuration` | delete | proposed | `DELETE /headless/invoke/platform/timeline/delete-timeline-configuration` | `get-timeline-object-definitions` |
-| `verify-delete-timeline-configuration` | verify | — | `GET /headless/invoke/platform/timeline/get-timeline-object-definitions` | `delete-timeline-configuration` |
-| `get-reference-fields-for-entity` | read | proposed | `GET /headless/invoke/platform/timeline/get-reference-fields-for-entity` | `get-anchor-object` |
-| `get-related-entities-of-anchor-entity` | read | proposed | `GET /headless/invoke/platform/timeline/get-related-entities-of-anchor-entity` | `get-anchor-object` |
-| `get-parent-objects-of-anchor-entity` | read | proposed | `GET /headless/invoke/platform/timeline/get-parent-objects-of-anchor-entity` | `get-anchor-object` |
-| `get-related-crm-objects-of-anchor-entity` | read | proposed | `GET /headless/invoke/platform/timeline/get-related-crmobjects-of-anchor-entity` | `get-anchor-object`, `get-data-spaces` |
-| `get-related-entity-for-preview` | read | proposed | `GET /headless/invoke/platform/timeline/get-related-entity-for-preview` | `get-related-entities-of-anchor-entity` |
-| `get-event-object-details` | read | proposed | `GET /headless/invoke/platform/timeline/get-event-object-details` | `get-related-entities-of-anchor-entity` |
-| `get-dmo-object-api-name` | read | proposed | `GET /headless/invoke/platform/timeline/get-dmo-object-api-name` | `get-related-crm-objects-of-anchor-entity` |
-| `get-cdp-screen-data-for-edit` | read | proposed | `GET /headless/invoke/platform/timeline/get-cdp-screen-data-for-edit` | `get-anchor-object`, `get-related-crm-objects-of-anchor-entity` |
-| `verify-set-timeline-configuration-active-status` | verify | — | `GET /headless/invoke/platform/timeline/get-timeline-object-definitions` | `set-timeline-configuration-active-status` |
-
-### Dependency graph
-
-```mermaid
-graph TD
-  is_data_space_enabled["is-data-space-enabled (read)"]
-  get_data_spaces["get-data-spaces (read)"]
-  get_timeline_org_pref["get-timeline-org-pref (read)"]
-  get_timeline_data_cloud_events_enabled["get-timeline-data-cloud-events-enabled (read)"]
-  get_timeline_data_graph_events_enabled["get-timeline-data-graph-events-enabled (read)"]
-  handle_timeline_toggle["handle-timeline-toggle (write)"]
-  verify_handle_timeline_toggle["verify-handle-timeline-toggle (verify)"]
-  get_timeline_limits["get-timeline-limits (read)"]
-  get_timeline_cdp_limits["get-timeline-cdp-limits (read)"]
-  get_anchor_object["get-anchor-object (read)"]
-  get_timeline_object_definitions["get-timeline-object-definitions (read)"]
-  save_timeline_configuration["save-timeline-configuration (write)"]
-  verify_save_timeline_configuration["verify-save-timeline-configuration (verify)"]
-  set_timeline_configuration_active_status["set-timeline-configuration-active-status (write)"]
-  delete_timeline_configuration["delete-timeline-configuration (delete)"]
-  verify_delete_timeline_configuration["verify-delete-timeline-configuration (verify)"]
-  get_reference_fields_for_entity["get-reference-fields-for-entity (read)"]
-  get_related_entities_of_anchor_entity["get-related-entities-of-anchor-entity (read)"]
-  get_parent_objects_of_anchor_entity["get-parent-objects-of-anchor-entity (read)"]
-  get_related_crm_objects_of_anchor_entity["get-related-crm-objects-of-anchor-entity (read)"]
-  get_related_entity_for_preview["get-related-entity-for-preview (read)"]
-  get_event_object_details["get-event-object-details (read)"]
-  get_dmo_object_api_name["get-dmo-object-api-name (read)"]
-  get_cdp_screen_data_for_edit["get-cdp-screen-data-for-edit (read)"]
-  verify_set_timeline_configuration_active_status["verify-set-timeline-configuration-active-status (verify)"]
-  is_data_space_enabled --> get_timeline_data_cloud_events_enabled
-  is_data_space_enabled --> get_timeline_data_graph_events_enabled
-  handle_timeline_toggle --> verify_handle_timeline_toggle
-  get_anchor_object --> save_timeline_configuration
-  save_timeline_configuration --> verify_save_timeline_configuration
-  save_timeline_configuration --> set_timeline_configuration_active_status
-  get_timeline_object_definitions --> delete_timeline_configuration
-  delete_timeline_configuration --> verify_delete_timeline_configuration
-  get_anchor_object --> get_reference_fields_for_entity
-  get_anchor_object --> get_related_entities_of_anchor_entity
-  get_anchor_object --> get_parent_objects_of_anchor_entity
-  get_anchor_object --> get_related_crm_objects_of_anchor_entity
-  get_data_spaces --> get_related_crm_objects_of_anchor_entity
-  get_related_entities_of_anchor_entity --> get_related_entity_for_preview
-  get_related_entities_of_anchor_entity --> get_event_object_details
-  get_related_crm_objects_of_anchor_entity --> get_dmo_object_api_name
-  get_anchor_object --> get_cdp_screen_data_for_edit
-  get_related_crm_objects_of_anchor_entity --> get_cdp_screen_data_for_edit
-  set_timeline_configuration_active_status --> verify_set_timeline_configuration_active_status
-```
-
-### Read operations
-
-#### `is-data-space-enabled`
-
-Read whether Data Cloud is enabled in the org. Required precondition for configuring Timeline Data Cloud / Data Graph events. Gated by Configure Data Cloud events on timeline.
-
-**Call:** `GET /headless/invoke/platform/timeline`   — status: `implemented`
-
-**Notes:** access_gating: A 403 {errorCode:ACCESS_DENIED} on this read means the org has NOT been provisioned for Data Cloud / data spaces (or the running user lacks data-space access) — it is an environmental precondition, NOT a broken endpoint. Confirmed live on hc-steelthread-test (403), consistent with get-timeline-data-cloud-events-enabled returning false on the same org. This read (and get-data-spaces) back the optional "Data Cloud events" section of the Timeline builder; the core Account-anchored CRM-event flow (get-anchor-object → get-event-object-details → save-timeline-configuration) does NOT depend on it. An agent should treat 403 here as "Data Cloud not enabled on this org" and skip the CDP branch, not retry.
-
-#### `get-data-spaces`
-
-List Data Cloud Data Spaces visible to Timeline configuration. Each space is a target for CDP-event mapping. Gated by Configure Data Cloud events on timeline.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-data-spaces`   — status: `implemented`
-
-**Notes:** access_gating: Same environmental gate as is-data-space-enabled: 403 {errorCode:ACCESS_DENIED} = Data Cloud / data spaces not provisioned on the org (or running user lacks access). Not a skill defect. Skip the Data Cloud events branch when this returns 403.
-
-#### `get-timeline-org-pref`
-
-Read the org-level Timeline preference flag (boolean). False means the feature is not enabled — configuration writes will fail until handle-timeline-toggle is invoked. Also serves as the verify read for handle-timeline-toggle.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-org-pref`   — status: `proposed`
-
-**Notes:** state_observation: Value on the target dev org has flipped from false (prior runs) to true this iteration.
-This confirms the one-way-enable invariant: once true, the preference cannot be toggled
-back to false via handle-timeline-toggle (500 CONTROLLER_ERROR "Timeline Org Preference
-cannot be disabled."). Agents that read false in a prior session and cache the value
-must re-read before deciding org readiness; the transition false → true is possible
-between sessions, the reverse is not.
-
-#### `get-timeline-data-cloud-events-enabled`
-
-Check whether the org permits Data Cloud events on Timeline. Wraps Configure Data Cloud timeline events (Customize Application or sysadmin + ManageTimeline).
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-data-cloud-events-enabled`   — status: `proposed`
-
-**Depends on:** `is-data-space-enabled`
-
-**Notes:** wire_contract: Returns a raw boolean literal in body (true|false). false means the Data-Cloud-events
-capability on Timeline is not enabled for this org — even when the org-level Timeline
-preference is true, agents that plan to add CDP-backed events to a configuration
-must gate on this read. Enablement is orthogonal to the base Timeline pref: Timeline
-can be on while DC events are off. Complementary to get-timeline-cdp-limits (which
-returns the numeric cap once the capability is on).
-
-#### `get-timeline-data-graph-events-enabled`
-
-Check whether Data Graph events on Timeline are permitted. Wraps Configure Data Graph timeline events; gated by Timeline access.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-data-graph-events-enabled`   — status: `proposed`
-
-**Depends on:** `is-data-space-enabled`
-
-**Notes:** wire_contract: Returns a raw boolean literal in body (true|false). false means Data Graph events
-on Timeline are not enabled for this org. Independent of both the base Timeline
-preference and the Data Cloud events capability. Read this before offering
-Data-Graph-derived events in a configuration payload.
-
-#### `get-timeline-limits`
-
-Read server-enforced numeric caps for CRM-event Timeline configuration (max events per anchor, max fields per event). Validate a config payload against these caps before save-timeline-configuration.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-limits`   — status: `proposed`
-
-**Notes:** wire_contract: Returns a fixed-shape JSON envelope carrying three integer caps on a Timeline
-configuration payload:
-  - TimelineEventLimit: 5   — maximum number of event sub-objects in one config
-  - TimelineConditionsLimit: 3 — maximum filter conditions per event
-  - TimelineRecordTypeLimit: 3 — maximum record-type filters per event
-Values are org-scoped and driven by the platform, not adjustable via SOR write.
-Agents constructing a save-timeline-configuration body must validate the event
-list length ≤ TimelineEventLimit and per-event condition/recordType arrays ≤
-their respective caps before dispatch — the write controller rejects
-over-limit payloads. Complementary to get-timeline-cdp-limits (which caps the
-CDP-backed event subtree separately).
-
-#### `get-timeline-cdp-limits`
-
-Read server-enforced numeric caps for Data Cloud / DMO event sources on a Timeline. Use alongside get-timeline-limits when the payload includes CDP events.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-cdplimits`   — status: `proposed`
-
-**Notes:** wire_contract: Returns a single-key JSON envelope `{"TimelineEventCDPLimit": 1}` — the cap on
-CDP-backed events per Timeline configuration on the current org. When
-get-timeline-data-cloud-events-enabled returns false this cap is still
-readable but not exercisable (the write path rejects CDP-flow events until the
-DC capability is on). Agents planning a mixed CRM + CDP event mix must gate
-their DC-event count on this limit AND on the DC-events-enabled flag before
-submitting a save-timeline-configuration body.
-
-#### `get-anchor-object`
-
-List entities allowlisted as Timeline anchor objects (TimelineSetupInfo entries: value=entity api-name, label=display name). Allowlist is server-controlled — not all sObjects qualify; treat as the authoritative input list for the anchor selector.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-anchor-object`   — status: `proposed`
-
-**Output:** List<TimelineSetupInfo>: each item carries value=entity api-name and label=display name. Server-controlled allowlist of Timeline-anchor-eligible entities.
-
-**Notes:** wire_contract: Returns a list of `{value, label}` entries where `value` is the entity API name and
-`label` is the human-readable entity label. The list is the Timeline-specific anchor
-allowlist (Account, AccountContactRelation, Accreditation, ActionPlan, ActionVisibility,
-and many more). Members of this list are the only valid values for the write-side
-TimelineObjectName field on save-timeline-configuration; sending a value outside the
-allowlist returns a server-side rejection. The full list is dynamic (governed by
-org licensing + Health Cloud add-ons) — always call this step live, do not cache.
-
-#### `get-timeline-object-definitions`
-
-List saved Timeline definitions paged by offset (returns generic field-bag entries with anchor entity, label, isActive, RecordId). The Connect API /connect/timeline/metadata/configurations only fetches by fullNames[] — does NOT page across all configurations. Coverage_gap filed for missing offset-paged Connect API.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-object-definitions`   — status: `proposed`
-
-**Inputs:**
-
-- `offset` *(`int`)*
-
-**Notes:** wire_contract: Returns an array of saved Timeline definitions, offset-paged. Each entry is a
-field-bag: `{RecordId, MasterLabel, DeveloperName, BaseObject, IsActive,
-LastModifiedDate, Definition}` where BaseObject is the anchor entity API name
-and Definition is a JSON blob of the persisted config body. On a fresh Health
-Cloud scratch org the endpoint returns 4 seeded configs all anchored on
-Account: HC_Assessments, HC_Clinical_Data, HC_Engagement_Data,
-HC_Patients_Life_Story — all IsActive=true. Agents building a clean-slate
-Timeline flow on HC should treat these as immovable unless the caller
-explicitly asks to deactivate + delete them (see delete-timeline-configuration
-notes).; variant_paging: offset is the ONLY page control — there is no limit/pageSize input; the server
-chooses the page size. Empty response (past the end) is `[]`, not an error.
-Read-only endpoint; do NOT use for fetch-by-Id (no filter inputs). To resolve
-a single definition by name, page from offset 0 and filter client-side, or
-pass the RecordId through save-timeline-configuration's edit branch.; write_side_field_mapping: Read-side BaseObject maps directly to write-side BaseObject on save-timeline-configuration.config — NO field name transformation is needed when round-tripping a definition through edit. (The autonomous pass had inferred a BaseObject→TimelineObjectName transform; that was disproven live — sending TimelineObjectName is silently ignored and the controller rejects with "required fields are missing: TimelineObjectName". See save-timeline-configuration.required_fields_wall for the proven anchor key.); list_shape_correction: CORRECTION (proven): the list entries carry header fields only — {Id, MasterLabel, DeveloperName, BaseObject, IsActive, LastModifiedDate}. There is NO `Definition` blob in the list response (the inferred contract claimed one). To read a config's full persisted Definition (the timeline/anchorObject/events subtree), SOQL the TimelineObjectDefinition sObject directly: SELECT Id, MasterLabel, DeveloperName, BaseObject, IsActive, Definition FROM TimelineObjectDefinition WHERE DeveloperName=... (Definition is a textarea holding the JSON). The list `Id` is the value to pass as config.RecordId on the save (edit) branch and as the RecordId query param on delete-timeline-configuration.
-
-#### `get-reference-fields-for-entity`
-
-List reference (lookup) fields on entityApiName, filtered against existing Timeline definitionId to avoid event-type collisions. Used to wire event entities into a Timeline's event-list.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-reference-fields-for-entity`   — status: `proposed`
-
-**Inputs:**
-
-- `entityApiName` *(`String`)*
-- `definitionId` *(`String`)*
-
-**Depends on:** `get-anchor-object`
-
-**Notes:** wire_contract: Returns an array of field-descriptor entries. Shape depends on the definitionId
-input:
-  - definitionId empty ("") → array of 6 datetime fields on the entity
-    (ClosedDate, CreatedDate, LastModifiedDate, LastReferencedDate,
-    LastViewedDate, SystemModstamp). These are the fields eligible for use as
-    the Timeline event date anchor.
-  - definitionId set to a real config Id → array carries the same 6 datetime
-    fields PLUS the full config record itself appended as the final element
-    (Definition JSON blob + IsActive + MasterLabel + BaseObject + etc). This
-    union shape lets the edit screen render both the "field to pick" list and
-    the "current definition state" in a single call.
-Agents constructing a fresh event should pass definitionId="". Agents editing an
-existing event should pass the config Id and read both the field candidates and
-the current definition state from one payload.
-
-#### `get-related-entities-of-anchor-entity`
-
-List event-eligible child entities for the anchor entityApiName (children with a lookup back to it). Each entry (TimelineSetupEventInfo): value=child entity api-name, label, referenceField=FK on the child.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-related-entities-of-anchor-entity`   — status: `proposed`
-
-**Inputs:**
-
-- `entityApiName` *(`String`)*
-
-**Depends on:** `get-anchor-object`
-
-**Output:** List<TimelineSetupEventInfo>: each item carries value=child entity api-name, label, referenceField=FK on the child pointing back to the anchor. Drives downstream get-event-object-details + get-related-entity-for-preview.
-
-**Notes:** factory_gap: Endpoint returns HTTP 500 CONTROLLER_ERROR on a well-formed Account anchor input
-(entityApiName=Account) on the current dev org. Reproduced across multiple
-runs — indicates a defect in the related-entities lookup path, not a transient
-state. Agents assembling a save-timeline-configuration payload that requires
-the related-entity list must fall back to a client-side computation from
-get-parent-objects-of-anchor-entity (parents) + Tooling API describe (children)
-until the underlying issue is fixed server-side. This is not the same NPE as
-get-related-crm-objects-of-anchor-entity — the failure mode here is a distinct
-controller-layer error, not the app-context helper NPE.
-
-#### `get-parent-objects-of-anchor-entity`
-
-List parent entities the anchor entityApiName looks up to (TimelineSetupParentObjectInfo: value, label, domain). Throws CannotFetchParentObjectsError on null/blank input.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-parent-objects-of-anchor-entity`   — status: `proposed`
-
-**Inputs:**
-
-- `entityApiName` *(`String`)*
-
-**Depends on:** `get-anchor-object`
-
-**Notes:** wire_contract: Returns an array of `{fieldName, fieldLabel, referenceTo, referenceToLabel}` entries
-describing the lookup parents on the anchor entity. For Account on Health Cloud orgs
-the response contains 7 entries: MasterRecordId→Account, RecordTypeId→RecordType,
-ParentId→Account, OwnerId→User, PersonContactId→Contact, PersonIndividualId→Individual,
-OperatingHoursId→OperatingHours. The PersonContactId and PersonIndividualId tokens
-appear when the org has Person Accounts enabled (typical for HC scratch orgs
-provisioned with HealthCloudAddOn); agents must not assume their absence.; error_contract: Passing an empty string for entityApiName returns HTTP 500 with response message
-"Something went wrong while loading objects. Try again." — the actual customer-facing
-text, not a typed error code. Agents should validate entityApiName is non-empty
-(a member of get-anchor-object) before dispatching this read.
-
-#### `get-related-crm-objects-of-anchor-entity`
-
-List CRM objects related to the anchor (entityApiName + entityLabel) for CDP/Data-Cloud event mapping. Each entry (TimelineSetupRelationshipObjectInfo) carries domain, domainLabel, relationship — used to map a CRM object to its DMO counterpart in a CDP-event Timeline.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-related-crmobjects-of-anchor-entity`   — status: `proposed`
-
-**Inputs:**
-
-- `entityApiName` *(`String`)*
-- `entityLabel` *(`String`)*
-
-**Depends on:** `get-anchor-object`, `get-data-spaces`
-
-**Output:** List<TimelineSetupRelationshipObjectInfo>: each item carries value=CRM api-name, label, domain, domainLabel, relationship — the CRM-to-DMO mapping inputs for CDP-event Timelines.
-
-**Notes:** factory_gap: Endpoint currently returns HTTP 500 with an internal null-pointer error in the
-application-context helper on the target dev org. Reproduced on inputs
-(entityApiName=Account, entityLabel=Account). The failure prevents the CDP-flow
-UI screen from populating the related-CRM-object picker; agents attempting to
-assemble a save-timeline-configuration payload for a CDP-backed event must fall
-back to a manual lookup of related-CRM entities until the underlying null path
-is guarded server-side. Companion endpoint get-cdp-screen-data-for-edit fails
-with the same root cause — the fix likely applies to both.
-
-#### `get-related-entity-for-preview`
-
-Return a single TimelineSetupEventInfo for entityApiName (value, label, referenceField). Drives the wizard preview pane — call after get-related-entities-of-anchor-entity to detail one chosen event entity.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-related-entity-for-preview`   — status: `proposed`
-
-**Inputs:**
-
-- `entityApiName` *(`String`)*
-
-**Depends on:** `get-related-entities-of-anchor-entity`
-
-**Notes:** error_contract: Single-input GET with only entityApiName populated returns HTTP 500 with response
-message "Unable to fetch Field to preview." Suggests the endpoint requires an
-additional field-selection input beyond entityApiName — the preview surface is
-field-scoped, not entity-scoped alone. Until the missing input is characterized,
-agents should treat this step as advisory only; the preview UI can be built by
-assembling field-descriptor data from get-event-object-details instead.
-
-#### `get-event-object-details`
-
-Bundle metadata for the event entity eventObjectName (TimelineSetupEventDetailsInfo): fields with data type, relatedLists, recordTypeDetails, indexedFieldsDetails. Composite shape — reconstructing from raw Tooling requires 3-4 calls + cross-record-type joins.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-event-object-details`   — status: `proposed`
-
-**Inputs:**
-
-- `eventObjectName` *(`String`)*
-
-**Depends on:** `get-related-entities-of-anchor-entity`
-
-**Output:** TimelineSetupEventDetailsInfo: fields[] (with data type), relatedLists[], recordTypeDetails[] (record-type metadata), indexedFieldsDetails (object). Inherits value+label+referenceField from TimelineSetupEventInfo.
-
-**Notes:** wire_contract: Returns a rich JSON payload with four sub-shapes:
-  - relatedLists: array of child-relationship entries reachable from the event object
-  - recordTypeDetails: map of record-type-id → developer-name / label / defaultness
-  - fields: array of field-descriptor entries with type, label, referenceTo
-  - indexedFieldsDetails: array of picklist fields (Origin, Status, Priority, Reason,
-    Type on Case) with their allowed values enumerated
-On Case anchored orgs this endpoint returns ~35 relatedLists and ~35 fields. The
-indexedFieldsDetails picklist enumeration is the source of truth for populating the
-save-timeline-configuration event-condition filter dropdowns — do NOT synthesize
-picklist values elsewhere (Tooling PicklistValue is unfiltered and includes inactive
-entries).
-
-#### `get-dmo-object-api-name`
-
-Return the DMO api-name (string) mapped to a CRM entityApiName (1:1 helper for the CDP path). Pairs with get-related-crm-objects-of-anchor-entity.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-dmo-object-api-name`   — status: `proposed`
-
-**Inputs:**
-
-- `entityApiName` *(`String`)*
-
-**Depends on:** `get-related-crm-objects-of-anchor-entity`
-
-**Notes:** wire_contract: Returns a raw string in body — the DMO (Data Model Object) API name mapped to the
-given CRM entity. When the entity has no DMO mapping the body is the empty string
-`""` (an empty JSON string literal, NOT null and NOT a 404). Agents should treat
-an empty string as "no mapping present" and skip the CDP-event branch for that
-anchor. On the target dev org Account currently returns `""` — Health Cloud DMO
-binding is not yet configured.
-
-#### `get-cdp-screen-data-for-edit`
-
-Return a composite map keyed crmObjectOfAnchorEntity + dmoObjectApiName for the edit wizard's CDP screen. Inputs: entityApiName + entityLabel + selectedRelatedCrmObject. Consolidates two upstream calls (CRM-objects + DMO-name) into one composite.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-cdp-screen-data-for-edit`   — status: `proposed`
-
-**Inputs:**
-
-- `entityApiName` *(`String`)*
-- `entityLabel` *(`String`)*
-- `selectedRelatedCrmObject` *(`String`)*
-
-**Depends on:** `get-anchor-object`, `get-related-crm-objects-of-anchor-entity`
-
-**Output:** Map<String,Object> with two keys: crmObjectOfAnchorEntity, dmoObjectApiName — composite consolidating get-related-crm-objects-of-anchor-entity + get-dmo-object-api-name for the edit wizard.
-
-**Notes:** factory_gap: Endpoint currently returns HTTP 500 with an internal null-pointer error in the
-application-context helper on the target dev org. Reproduced on inputs
-(entityApiName=Account, entityLabel=Account, selectedRelatedCrmObject=Contact).
-This is the same root cause as get-related-crm-objects-of-anchor-entity — the
-CDP-flow edit screen cannot be assembled until the underlying application-context
-helper is fixed to guard against a null app-info reference.
-
-### Write operations
-
-#### `handle-timeline-toggle`
-
-Enable the Timeline org preference. Only value=true is accepted; sending value=false throws CannotTurnPrefOffError (one-way enable invariant). Required once per org before any save-timeline-configuration call. AURA-IS-CANONICAL — no public Connect/Tooling/Metadata alternative; controller enforces the one-way control.
-
-**Call:** `PATCH /headless/invoke/platform/timeline/handle-timeline-toggle`   — status: `proposed`
-
-**Inputs:**
-
-- `value` *(`boolean`)* — Toggle the value preference on or off.
-
-**Notes:** one_way_enable_invariant: This endpoint enables the org-level Timeline preference. It is a ONE-WAY
-control: PATCH with the "enable" payload flips the pref from false → true
-and returns 200. PATCH with a "disable" payload against an already-enabled
-org is server-rejected with HTTP 500 CONTROLLER_ERROR "Timeline Org
-Preference cannot be disabled." — there is no admin-callable path back to
-false. Agents driving this step must confirm the caller understands the
-commitment before dispatch, and must always precede the call with
-get-timeline-org-pref to avoid an unnecessary write (idempotent on
-already-true state, but wasteful).; companion_read: Chain with verify-handle-timeline-toggle (or get-timeline-org-pref directly)
-immediately after the write to confirm true state before proceeding to
-Timeline configuration writes.
-
-#### `save-timeline-configuration`
-
-Create a Timeline definition (omit RecordId in config) or update an existing one (supply RecordId). Throws DuplicateApiNameError when developer name collides. Returns the saved record id (Map<String,String>). AURA-IS-CANONICAL — no public CRUD on TimelineMetadataDefinition; coverage_gap filed.
-
-**Call:** `PATCH /headless/invoke/platform/timeline/save-timeline-configuration`   — status: `proposed`
-
-**Inputs:**
-
-- `config` *(`LinkedHashMap<String, Object>`)* — Value for config.
-
-**Depends on:** `get-anchor-object`
-
-**Notes:** required_fields_wall: CORRECTION (proven, supersedes the inferred key name): the create body is a `config` map whose keys map 1:1 to the TimelineObjectDefinition sObject fields, NOT a custom envelope. The minimum required-field wall is:
-  - MasterLabel   (human-readable name)
-  - DeveloperName (api-safe token, unique across TimelineObjectDefinition;
-                   DuplicateApiNameError on collision — page
-                   get-timeline-object-definitions to check)
-  - BaseObject    (anchor entity API name — MUST be a member of
-                   get-anchor-object's allowlist). The anchor key is
-                   `BaseObject`, NOT `TimelineObjectName`: sending
-                   TimelineObjectName is silently ignored and the controller
-                   rejects with "required fields are missing: TimelineObjectName".
-  - Definition    (the events/anchor subtree — see create_body_shape; the
-                   controller rejects with "Specify a definition for the
-                   <label> timeline" when omitted)
-IsActive (boolean) is optional at create; defaults per platform.; create_vs_update_branching: The same PATCH endpoint handles both create and update:
-  - Create: omit `config.RecordId` entirely. Response is `{"RecordId":
-    "<newId>"}` on success.
-  - Update: supply `config.RecordId` from a prior get-timeline-object-definitions
-    page. Response echoes the same RecordId.
-Sending an empty-string RecordId (`""`) triggers the update branch and errors
-because the empty Id does not resolve — always omit the key for create.; event_subtree_shape: SUPERSEDED — the inferred `config.events[]` shape (with EventObjectName / conditions[] / recordTypes[] at the event root) is NOT what the controller accepts. See `create_body_shape` for the proven structure: events live at config.Definition.timeline.events[], each wrapped in `oneToMany.eventObject`, the per-event condition key is `filters` (not `conditions`), and recordTypes nests inside eventObject.; create_body_shape: CORRECTION (proven, supersedes inferred `config.events[]` / `event_subtree_shape`): `config.Definition` is a nested MAP (LinkedHashMap), NOT a JSON string and NOT a bare `events` array. Passing a JSON string fails with "class java.lang.String cannot be cast to class java.util.LinkedHashMap". The proven structure is:
-  config:
-    MasterLabel: <str>
-    DeveloperName: <str, unique>
-    BaseObject: <anchor API name, e.g. Account>
-    IsActive: <bool>
-    Definition:
-      timeline:
-        anchorObject:
-          object: {entity: <BaseObject>, label: <label>, source: "", icon: ""}
-        age: {field: ""}
-        events:
-          - oneToMany:
-              eventObject:
-                name: <event object API name>
-                recordTypes: []            # array; caps at TimelineRecordTypeLimit (3)
-                fieldsToDisplay: [{field,label,type}, ...]
-                relatedlistsToDisplay: [{entity,label}, ...]
-                title: {field,label,type}
-                subTitle: {field,label,type}
-              filters: []                  # per-event condition list (NOT "conditions");
-                                           # caps at TimelineConditionsLimit (3)
-              sort: {field,label,type}
-              anchorReferenceField: {field,label,type}
-events[] length caps at TimelineEventLimit (5, from get-timeline-limits). The Definition field `type` values are the display types, mapped from the event object's field dataType: REFERENCE→EntityId, STRING→Text, PICKLIST→DynamicEnum, DATE/DATETIME→DateTime.; anchor_reference_field_rule: Each event's `anchorReferenceField.field` (and any reference in fieldsToDisplay) MUST be the real field API name, NOT the relationship alias. Create-time validation resolves against fieldApiName and rejects the alias with "Error resolving Entity/Field Names. Could not resolve fieldApiName: <alias> for entityApiName: <event>". Example: on CareProgramEnrollee use `AccountId` (the read side / stored Definition shows the alias "Account", which fails on create); on ClinicalEncounter the patient anchor is `PatientId` (labelled "Account ID"). Source the correct field names from get-event-object-details (fields[].value).; proven_north_star_example: PROVEN end-to-end (Account-anchored patient timeline showing Clinical Encounters + Care Plan events). config = {MasterLabel:"R2D2 Clinical + Care Plan", DeveloperName:"R2D2_CE_CarePlan_Verify", BaseObject:"Account", IsActive:true, Definition:{timeline:{anchorObject:{object:{entity:"Account", label:"Account",source:"",icon:""}}, age:{field:""}, events:[
-  {oneToMany:{eventObject:{name:"ClinicalEncounter",recordTypes:[],
-    fieldsToDisplay:[{field:"Status",label:"Status",type:"DynamicEnum"}],
-    relatedlistsToDisplay:[],title:{field:"Name",label:"Name",type:"Text"},
-    subTitle:{field:"Status",label:"Status",type:"DynamicEnum"}},filters:[],
-    sort:{field:"StartDate",label:"Start Date",type:"DateTime"},
-    anchorReferenceField:{field:"PatientId",label:"Account ID",type:"EntityId"}}},
-  {oneToMany:{eventObject:{name:"CareProgramEnrollee",recordTypes:[],
-    fieldsToDisplay:[{field:"Status",label:"Status",type:"DynamicEnum"}],
-    relatedlistsToDisplay:[],title:{field:"Name",label:"Name",type:"Text"},
-    subTitle:{field:"Status",label:"Status",type:"DynamicEnum"}},filters:[],
-    sort:{field:"CreatedDate",label:"Created Date",type:"DateTime"},
-    anchorReferenceField:{field:"AccountId",label:"Account ID",type:"EntityId"}}}
-]}}}. Returned 200 {RecordId}. NOTE: Health Cloud has no standalone `CarePlan` object (get-event-object-details returns CONTROLLER_ERROR for CarePlan/CareVisit/HealthcareEncounter); the patient-level "care plan" event is CareProgramEnrollee (the patient's care-program enrollment). CareProgram references Account only as SponsorId (program sponsor, not the patient).; create_vs_update_confirmed: CONFIRMED live (was inferred): omit config.RecordId → create, response {RecordId:<newId>}. Supply config.RecordId → update, response echoes the same RecordId. Both branches share this one PATCH endpoint.
-
-#### `set-timeline-configuration-active-status`
-
-Toggle isActive on a saved Timeline definition (RecordId + isActivated). Activating makes the Timeline visible on its anchor entity's record pages. AURA-IS-CANONICAL — no public Tooling/sObject CRUD on the underlying record.
-
-**Call:** `PATCH /headless/invoke/platform/timeline/set-timeline-configuration-active-status`   — status: `proposed`
-
-**Inputs:**
-
-- `RecordId` *(`String`)* — Id of the record.
-- `isActivated` *(`boolean`)* — Whether activated is enabled.
-
-**Depends on:** `save-timeline-configuration`
-
-**Notes:** wire_contract: Request body is a two-field envelope `{"RecordId": <configId>, "isActivated": <bool>}`.
-On success returns HTTP 200 with body `{"LastModifiedDate": <ISO datetime>,
-"RecordId": <configId>}`. Idempotent when `isActivated` matches the current state
-(re-activating an already-active config returns 200 with a fresh LastModifiedDate).; error_contract: Unknown RecordId (well-formed 18-char Id that does not resolve) returns HTTP 500
-with response message "Timeline configuration not found." Malformed Id shape
-typically returns a validation error from the dispatcher layer before reaching
-the controller. Agents should validate the RecordId format client-side before
-dispatching this write.; companion_precondition_for_delete: This step is a mandatory precondition for delete-timeline-configuration on any
-currently-active config: the delete controller rejects active configs. Call
-set-timeline-configuration-active-status with isActivated=false first, then
-delete-timeline-configuration.
-
-### Verify operations
-
-#### `verify-handle-timeline-toggle`
-
-Read getTimelineOrgPref to confirm handle-timeline-toggle persisted. Expects true; a false read indicates the toggle did not commit.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-org-pref`
-
-**Depends on:** `handle-timeline-toggle`
-
-#### `verify-save-timeline-configuration`
-
-Page through saved Timeline definitions (offset=0) and confirm the RecordId returned from save-timeline-configuration is present with the expected masterLabel/fullName.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-object-definitions`
-
-**Depends on:** `save-timeline-configuration`
-
-#### `verify-delete-timeline-configuration`
-
-Page through saved Timeline definitions (offset=0) and confirm the RecordId from delete-timeline-configuration is no longer present.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-object-definitions`
-
-**Depends on:** `delete-timeline-configuration`
-
-#### `verify-set-timeline-configuration-active-status`
-
-Page saved Timeline definitions (offset=0) and confirm the RecordId touched by set-timeline-configuration-active-status now reports the expected isActive value. Pair-by-semantic-match: names don't share a stem so the deterministic verify-synth skipped this.
-
-**Call:** `GET /headless/invoke/platform/timeline/get-timeline-object-definitions`
-
-**Depends on:** `set-timeline-configuration-active-status`
-
-### Destructive operations
-
-#### `delete-timeline-configuration`
-
-Delete a saved Timeline definition by RecordId. Destructive — no soft-delete. AURA-IS-CANONICAL — no public CRUD alternative.
-
-**Call:** `DELETE /headless/invoke/platform/timeline/delete-timeline-configuration`   — status: `proposed`
-
-**Inputs:**
-
-- `RecordId` *(`String`)*
-
-**Depends on:** `get-timeline-object-definitions`
-
-**Notes:** precondition_deactivate_first: Deleting an ACTIVE Timeline configuration is server-rejected. HTTP DELETE against
-a config whose IsActive=true returns HTTP 500 with response message
-"You can't delete the active timeline configuration <MasterLabel>. Deactivate
-the configuration and try again." (with <MasterLabel> substituted from the
-target record). This applies to ALL configs including the four pre-seeded HC
-configs (HC_Assessments, HC_Clinical_Data, HC_Engagement_Data,
-HC_Patients_Life_Story), all of which ship IsActive=true — meaning none of them
-can be removed by a single delete call. To remove any active config, agents
-must first call set-timeline-configuration-active-status with isActivated=false
-for that RecordId, then re-issue delete-timeline-configuration.; seeded_hc_configs_are_active: On Health Cloud orgs the four pre-seeded HC configs (HC_Assessments,
-HC_Clinical_Data, HC_Engagement_Data, HC_Patients_Life_Story) all ship
-IsActive=true. Attempts to delete any of them fail with the message above until
-deactivation. This is a Health-Cloud-specific gotcha for admins scripting a
-clean-slate Timeline setup.