@salesforce/afv-skills 1.67.0 → 1.68.0

package/skills/platform-report-generate/references/verification-checklist.md

@@ -2,6 +2,9 @@
 
 Run through these checks before deploying any generated report metadata.
 
+## Before Writing the XML
+- [ ] Check every `<field>` in `<columns>`, `<groupingsDown>`, and `<groupingsAcross>`, every filter `<column>`, and the chart `<groupingColumn>` against the column table for the report type in `references/column-names.md` (or the MCP column list). No bare `NAME` or `USERS.NAME` — use the report type's name column (e.g. `OPPORTUNITY_NAME`, `FULL_NAME`, `OWNER`, `FIRST_NAME` + `LAST_NAME`)
+
 ## Universal Checks
 - [ ] File extension is `.report-meta.xml`
 - [ ] File is placed under `<sourceDir>/reports/<FolderName>/` (check sfdx-project.json for source path)
@@ -13,6 +16,8 @@ Run through these checks before deploying any generated report metadata.
 - [ ] `<description>` explains the business purpose (max 255 chars)
 - [ ] All column `<field>` values use correct platform column names
 - [ ] Custom field columns use `<ObjectApiName>.<FieldApiName__c>` format
+- [ ] Each `<columns>` contains exactly one `<field>`
+- [ ] Custom report type: `<reportType>` ends in `__c` and every column uses a `<table>$<field>` path from the report type's sections
 
 ## Format-Specific Checks
 - [ ] Tabular: no `<groupingsDown>`, no `<groupingsAcross>`, no `<chart>`, no `<aggregateTypes>`
@@ -28,6 +33,7 @@ Run through these checks before deploying any generated report metadata.
 - [ ] `<timeFrameFilter>` uses a valid `<interval>` value from `references/date-intervals.md`
 - [ ] Date columns use platform column names (e.g. `CLOSE_DATE`, not `CloseDate`)
 - [ ] Multi-value picklist uses ONE criteriaItem with comma-separated values
+- [ ] No `<params>` the request didn't ask for; Opportunity `probability` param is only `>0`
 
 ## Grouping Checks
 - [ ] `<dateGranularity>` is set for every grouping (use `None` for non-date fields)
@@ -38,8 +44,10 @@ Run through these checks before deploying any generated report metadata.
 - [ ] Chart is only on Summary or Matrix report
 - [ ] `<chartType>` is a valid type from `references/chart-types.md`
 - [ ] `<groupingColumn>` matches a grouping field
-- [ ] `<chartSummaries>` contains valid `<aggregate>` + `<column>` (or just `<column>RowCount</column>`)
-- [ ] `legendPosition` only used with grouped/stacked charts
+- [ ] `<chartSummaries>` contains valid `<aggregate>` + `<column>`, or ONLY `<column>RowCount</column>` with no `<aggregate>`
+- [ ] No `<columns><field>RowCount</field></columns>` — `RowCount` is only valid in `<chartSummaries><column>`, `<sortByName>`, or a `<calculatedFormula>`
+- [ ] `legendPosition` omitted on single-series `HorizontalBar`/`VerticalColumn`/`Line`; on grouped/stacked charts only `Right` or `Bottom` (see `references/chart-types.md`)
+- [ ] Every `<chart>` child element is in the allowed list in `references/chart-types.md`
 
 ## Cross-Filter Checks (if applicable)
 - [ ] Maximum 3 cross-filters per report

package/skills/service-digital-engagement-channel-configure/SKILL.md

@@ -138,6 +138,8 @@ All steps are sequential. Do not skip or reorder.
    - `isSaveTranscriptEnabled` — save conversation transcripts
    - `maxFileSize` — maximum attachment size in MB
 
+9a. **Configure session inactivity (optional)** — ask using the Setup labels and set the top-level fields per `references/channel_settings.md` → "Setup Prompts: Session Inactivity".
+
 10. **Configure messaging keywords** — generate `<messagingKeywords>` elements:
     - `OptOut` type with individual `<keyword>` elements: cancel, end, quit, stop, stopall, unsubscribe
     - `Help` type with `<keyword>`: help
@@ -176,7 +178,7 @@ All steps are sequential. Do not skip or reorder.
 17. **Report** — delegated: return the contract §5 result and stop. Standalone: continue.
 
 18. **Present output** (standalone) — show the generated file to the user with a summary of configured settings and confirm activation status. Offer next steps:
-    - **Automated responses** — ask if the user wants to configure `<automatedResponses>` (OptOutConfirmation, HelpResponse). If yes, generate elements with `autoResponseContentType: TextResponse`, `language`, and XML-escaped `response` text, then redeploy.
+    - **Automated responses** — ask which messages the user wants using the Setup labels per `references/channel_settings.md` → "Setup Prompts: Automated Responses", then redeploy.
 
 ---
 
@@ -219,7 +221,7 @@ All steps are sequential. Do not skip or reorder.
 | Custom parameters not collected | `name` must be unique per channel |
 | `<customParameters>` deploy fails: "bad value for restricted picklist field" | `parameterDataType` was set to something other than `String`. Channel custom parameters are always `String`; set the field's actual type (Number, Checkbox, dropdown) at the deployment level, not here |
 | Removing a custom parameter: "can't be deleted as it is referenced elsewhere" | **Check before deploying, not after.** Every deployment on this channel whose pre-chat form uses the param must first drop that field and be published (user-approved); remove the param's `actionParameterMappings` in a separate deploy first. See `references/channel_settings.md` §Removing a Custom Parameter |
-| Automated responses not showing | Use exact `type` values (`OptOutConfirmation`, `HelpResponse`); XML-escape special characters |
+| Automated response / session-inactivity deploy fails | See `references/channel_settings.md` → "Automated Responses", "Session Settings" |
 | Channel deployed but messages not routing | Channel must be activated after deployment — it defaults to inactive |
 | "You can't enable Session-Based Chat for verified users" | Set `isSynchronousChatEnabled` to `false` for Auth channels — session-based chat is only valid for UnAuth |
 
@@ -252,9 +254,8 @@ All steps are sequential. Do not skip or reorder.
 - [ ] If UnAuth, is `anonymousUserJwtExpirationTime` set (default 360, range 60-4320)?
 - [ ] If Auth, is `verifiedUserJwtExpirationTime` set (default 60, range 60-240)?
 
-### Automated Response Checks (only if user requested)
-- [ ] Do all `type` values use valid IDs (`OptOutConfirmation`, `HelpResponse`)?
-- [ ] Are special characters XML-escaped in `response` text?
+### Session Inactivity / Automated Response Checks (only if user requested)
+- [ ] Checked against `references/channel_settings.md` (Session Settings, Automated Responses)?
 
 ### Keyword Checks
 - [ ] Is there at least an `OptOut` keyword type defined?
@@ -283,6 +284,7 @@ File structure follows the template in `assets/messaging_channel_template.xml`.
 | Creating the Omni-Channel Flow for routing | `automation-flow-generate` skill |
 | Creating permission sets for messaging agents | `platform-permission-set-generate` skill |
 | Creating the Embedded Service Deployment | `service-digital-engagement-deployment-configure` skill |
+| Creating the `ConversationMessageDefinition` an automated response references | `conversation-message-definition-builder` skill |
 
 ---
 

package/skills/service-digital-engagement-channel-configure/assets/messaging_channel_template.xml

@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <MessagingChannel xmlns="http://soap.sforce.com/2006/04/metadata">
     <!-- Automated Responses (optional, repeat per response) -->
+    <!-- Shape depends on type — see references/channel_settings.md "Automated Responses" -->
+    <!-- TextResponse shape: OptOutConfirmation, HelpResponse only -->
     <!--
     <automatedResponses>
         <autoResponseContentType>TextResponse</autoResponseContentType>
@@ -10,6 +12,18 @@
     </automatedResponses>
     -->
 
+    <!-- MessageDefinition shape: InitialResponse, AgentEngagedResponse, AgentEndEngagementResponse, EndUserInactiveResponse, EndUserIdleResponse, RerouteResponse, RoutingUnavailableResponse -->
+    <!-- messageDefinitionName must reference an existing ConversationMessageDefinition (build via conversation-message-definition-builder first) -->
+    <!-- Do NOT include language or response on this shape -->
+    <!-- Optional responseTimeoutInMins (4-30): only for EndUserIdleResponse / EndUserInactiveResponse -->
+    <!--
+    <automatedResponses>
+        <autoResponseContentType>MessageDefinition</autoResponseContentType>
+        <messageDefinitionName>{CONVERSATION_MESSAGE_DEFINITION_DEV_NAME}</messageDefinitionName>
+        <type>{InitialResponse|AgentEngagedResponse|AgentEndEngagementResponse|EndUserInactiveResponse|EndUserIdleResponse|RerouteResponse|RoutingUnavailableResponse}</type>
+    </automatedResponses>
+    -->
+
     <!-- Standard Parameters (optional, repeat per parameter) -->
     <!-- actionParameterMappings is optional — include when using Flow routing to map to flow input variables -->
     <!--
@@ -58,10 +72,29 @@
         <isFileAttachmentExtUnrestricted>{true|false}</isFileAttachmentExtUnrestricted>
         <isSaveTranscriptEnabled>{true|false}</isSaveTranscriptEnabled>
         <maxFileSize>{SIZE_IN_MB}</maxFileSize>
+
+        <!-- Messaging Authorizations (only when authMode is Auth; omit entirely for UnAuth) -->
+        <!--
+        <messagingAuthorizations>
+            <authIdentifier>{AUTH_IDENTIFIER}</authIdentifier>
+            <authorizationType>PublicKeyCertificateSet</authorizationType>
+            <enabled>{true|false}</enabled>
+            <publicKeyCertificateSetName>{KEYSET_NAME}</publicKeyCertificateSetName>
+        </messagingAuthorizations>
+        -->
     </embeddedConfig>
 
     <!-- Session Settings -->
     <endUserIdleTimeOut>{IDLE_TIMEOUT_MINUTES}</endUserIdleTimeOut>
+
+    <!-- Session Inactivity (optional) — top-level siblings of embeddedConfig, not nested inside it -->
+    <!-- endUserIdleAction must be Inactivate, End, or InactivateAndEnd -->
+    <!--
+    <endUserIdleAction>{Inactivate|End|InactivateAndEnd}</endUserIdleAction>
+    <endInactiveSessionTimeOut>{MINUTES_AFTER_IDLE_ACTION}</endInactiveSessionTimeOut>
+    <isAgentMessageResetInactivityEnabled>{true|false}</isAgentMessageResetInactivityEnabled>
+    -->
+
     <isEstimatedWaitTimeEnabled>{true|false}</isEstimatedWaitTimeEnabled>
     <isQueuePositionEnabled>{true|false}</isQueuePositionEnabled>
     <isSynchronousChatEnabled>{true|false}</isSynchronousChatEnabled>

package/skills/service-digital-engagement-channel-configure/references/channel_settings.md

@@ -133,12 +133,24 @@ Configures the authorization settings for verified user identity in the messagin
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `endUserIdleTimeOut` | Integer | `5` | Minutes of user inactivity before idle warning |
+| `endUserIdleTimeOut` | Integer | `5` | Minutes of user inactivity before idle warning (range 5-30) |
+| `endUserIdleAction` | Enum | — | Action taken when the idle timeout elapses: `Inactivate`, `End`, or `InactivateAndEnd` |
+| `endInactiveSessionTimeOut` | Integer | — | Minutes after `endUserIdleAction` fires before the inactive session itself ends |
+| `isAgentMessageResetInactivityEnabled` | Boolean | — | Restart the customer's inactivity timer when a rep sends a message (Setup label: "Rep messages reset customer's inactivity timer"). Only takes effect when `endUserIdleTimeOut` is set; it is forced to `false` otherwise |
 | `isEstimatedWaitTimeEnabled` | Boolean | `false` | Show estimated wait time |
 | `isQueuePositionEnabled` | Boolean | `false` | Show queue position to user |
 | `isSynchronousChatEnabled` | Boolean | `false` | Enable real-time synchronous chat |
 | `isVoiceModeEnabled` | Boolean | `false` | Enable voice mode capability |
 
+Setup UI (Customer Inactivity card): `endUserIdleTimeOut` is "Minutes to Inactivate Session" / "Minutes to End Session" (5-30); `endUserIdleAction` is "Choose action when customer is idle" with values "Inactivate Session" (`Inactivate`), "End Session" (`End`), and "Inactivate & End Session" (`InactivateAndEnd`); `endInactiveSessionTimeOut` is "Minutes to End Session After Inactivation" (5-30, only meaningful with `InactivateAndEnd`).
+
+`endUserIdleTimeOut`, `endUserIdleAction`, `endInactiveSessionTimeOut`, and `isAgentMessageResetInactivityEnabled` are **MIAW (EmbeddedMessaging) only** — not applicable to SMS/WhatsApp/LINE. These can be deployed together with `isAbandonedChatsEnabled`/`chatAbandonmentTimeout` with no conflict.
+
+```xml
+<endUserIdleTimeOut>5</endUserIdleTimeOut>
+<endUserIdleAction>InactivateAndEnd</endUserIdleAction>
+<endInactiveSessionTimeOut>10</endInactiveSessionTimeOut>
+```
 
 ---
 
@@ -237,30 +249,76 @@ A parameter still used by a pre-chat form can't be deleted ("can't be deleted as
 
 ## Automated Responses (`<automatedResponses>`)
 
-Repeatable element — automated messages sent at specific events.
+Repeatable element — automated messages sent at specific events. There are two mutually exclusive content shapes, and **which shape applies depends on the `type`** (EmbeddedMessaging channel).
+
+### Shape 1 — `TextResponse` (inline text)
+
+Applies only to `OptOutConfirmation` and `HelpResponse`.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `autoResponseContentType` | Enum | Yes | `TextResponse` or `MessageDefinition` |
+| `autoResponseContentType` | Enum | Yes | `TextResponse` |
 | `language` | String | Yes | Locale code (e.g., `en_US`) |
 | `response` | String | Yes | The response message text (XML-escape special chars) |
-| `type` | Enum | Yes | The event type — see table below |
+| `type` | Enum | Yes | `OptOutConfirmation` or `HelpResponse` |
+
+### Shape 2 — `MessageDefinition` (reference to a Messaging Component)
+
+Applies to `InitialResponse`, `AgentEngagedResponse`, `AgentEndEngagementResponse`, `EndUserInactiveResponse`, `EndUserIdleResponse`, `RerouteResponse`, and `RoutingUnavailableResponse` — the "Conversation Acknowledgement," "Start Conversation," "End Conversation," "Inactive Conversation," "Warning Message," "Reroute Conversation," and "Routing Unavailable" fields in the Setup UI, all backed by a "Messaging Components" (`ConversationMessageDefinition`) picker.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `autoResponseContentType` | Enum | Yes | `MessageDefinition` |
+| `messageDefinitionName` | String | Yes | `DeveloperName` of an existing `ConversationMessageDefinition`. Must already exist in the org — build it with the `conversation-message-definition-builder` skill before deploying this reference (see Cross-Skill Integration in SKILL.md) |
+| `type` | Enum | Yes | `InitialResponse`, `AgentEngagedResponse`, `AgentEndEngagementResponse`, `EndUserInactiveResponse`, `EndUserIdleResponse`, `RerouteResponse`, or `RoutingUnavailableResponse` |
+| `responseTimeoutInMins` | Integer | No | **Only** on `EndUserIdleResponse` and `EndUserInactiveResponse` (range 4-30). Minutes before the idle action fires at which the message is shown (Setup label "Minutes to Show Warning"; Help: "select 4 to show the message 4 minutes before the session inactivates"). On `EndUserIdleResponse` it must be less than `endUserIdleTimeOut` (Setup caps it at `endUserIdleTimeOut` - 1). Rejected on every other type and on `TextResponse` |
+
+**Do not include `<language>` or `<response>` on a `MessageDefinition`-shaped block.** The language comes from the referenced CMD's own `<language>` field. Including `<language>` here causes the deploy to fail — with `"unexpected metadata"` for `InitialResponse`/`AgentEngagedResponse`/`AgentEndEngagementResponse`, and with an internal server error for `EndUserInactiveResponse`. Omitting it is the fix, not a schema quirk to work around another way.
+
+```xml
+<!-- TextResponse shape -->
+<automatedResponses>
+    <autoResponseContentType>TextResponse</autoResponseContentType>
+    <language>en_US</language>
+    <response>Text STOP to opt out of further messages.</response>
+    <type>HelpResponse</type>
+</automatedResponses>
+
+<!-- MessageDefinition shape -->
+<automatedResponses>
+    <autoResponseContentType>MessageDefinition</autoResponseContentType>
+    <messageDefinitionName>Customer_Inactive_Message</messageDefinitionName>
+    <type>EndUserInactiveResponse</type>
+</automatedResponses>
+
+<!-- Idle warning with responseTimeoutInMins (only valid on EndUserIdleResponse / EndUserInactiveResponse) -->
+<automatedResponses>
+    <autoResponseContentType>MessageDefinition</autoResponseContentType>
+    <messageDefinitionName>Idle_Warning_Message</messageDefinitionName>
+    <responseTimeoutInMins>4</responseTimeoutInMins>
+    <type>EndUserIdleResponse</type>
+</automatedResponses>
+```
 
 ### Response Types
 
-| `type` Value | When Sent |
-|-------------|-----------|
-| `OptOutConfirmation` | When user opts out of receiving messages |
-| `HelpResponse` | When user sends a help keyword |
-| `InitialResponse` | Let a customer know that their initial message was received |
-| `AgentEngagedResponse` | Let a customer know that their messaging session was accepted by a service rep |
-| `AgentEndEngagementResponse` | Let a customer know that their messaging session ended, and optionally provide a post-chat URL. This auto-response is sent when the service rep or end user ends the session |
-| `EndUserInactiveResponse` | Let a customer know that their messaging conversation has ended because they stopped responding |
-| `EndUserIdleResponse` | When end user idle response |
+| `type` Value | Content Shape | When Sent |
+|-------------|---------------|-----------|
+| `OptOutConfirmation` | `TextResponse` | When user opts out of receiving messages |
+| `HelpResponse` | `TextResponse` | When user sends a help keyword |
+| `InitialResponse` | `MessageDefinition` | Let a customer know that their initial message was received |
+| `AgentEngagedResponse` | `MessageDefinition` | Let a customer know that their messaging session was accepted by a service rep |
+| `AgentEndEngagementResponse` | `MessageDefinition` | Let a customer know that their messaging session ended, and optionally provide a post-chat URL. Sent when the service rep or end user ends the session |
+| `EndUserInactiveResponse` | `MessageDefinition` | Let a customer know that their messaging conversation has ended because they stopped responding |
+| `EndUserIdleResponse` | `MessageDefinition` | Warn a customer that their conversation will be inactivated or ended because they are idle. Set in the Customer Inactivity card ("Warning Message"); `responseTimeoutInMins` is how many minutes before the idle action it is shown |
+| `RerouteResponse` | `MessageDefinition` | Sent when a conversation is rerouted to a different queue or agent ("Reroute Conversation") |
+| `RoutingUnavailableResponse` | `MessageDefinition` | Sent when no routing target is available ("Routing Unavailable") |
+
+Only `OptOutConfirmation` and `HelpResponse` use the `TextResponse` shape; every other type is `MessageDefinition`-only. `OptIn*` and `CustomResponse` types are not used for EmbeddedMessaging channels.
 
 ### XML Escaping
 
-Special characters in `response` must be XML-escaped:
+Special characters in a `TextResponse` block's `response` must be XML-escaped:
 - `'` → `&apos;`
 - `"` → `&quot;`
 - `&` → `&amp;`
@@ -303,3 +361,41 @@ Repeatable element — keyword groups that trigger automated responses. Each key
     <language>en_US</language>
 </messagingKeywords>
 ```
+
+---
+
+## Setup Prompts: Session Inactivity
+
+Ask using the Setup labels (Customer Inactivity card), with the field in parentheses:
+
+- "Inactivate or end a session after a period of customer inactivity?" If yes, "Minutes to Inactivate Session / End Session?" (`endUserIdleTimeOut`, 5-30).
+- "Choose action when customer is idle": **Inactivate Session** (`Inactivate`), **End Session** (`End`), or **Inactivate & End Session** (`InactivateAndEnd`) (`endUserIdleAction` — no other values). **Validate before editing or deploying:** if the user names any other value (e.g. `EndChatSession`, "close", "terminate"), do not write it; say it is not an option, list the three, and ask which one. Never deploy to see whether it is accepted. For Inactivate & End Session also ask "Minutes to End Session After Inactivation?" (`endInactiveSessionTimeOut`, 5-30).
+- "Should rep messages reset the customer's inactivity timer?" (`isAgentMessageResetInactivityEnabled`; needs `endUserIdleTimeOut`).
+- Optional idle warning: the **Warning Message** prompt under Automated Responses below.
+
+Set all of these as **top-level fields, siblings of `<embeddedConfig>`** (not nested inside it). MIAW (EmbeddedMessaging) only.
+
+Checks:
+- [ ] `endUserIdleAction`/`endInactiveSessionTimeOut` are top-level siblings of `<embeddedConfig>`, not nested inside it.
+- [ ] `endUserIdleAction` is one of `Inactivate`, `End`, `InactivateAndEnd`, checked before the file is edited (free text such as `EndChatSession` fails with "not a valid value for the enum").
+- [ ] `endUserIdleTimeOut` is in range 5-30.
+
+## Setup Prompts: Automated Responses
+
+Ask which messages the user wants, using the Setup labels (Automated Responses card), with the `type` in parentheses. Two content shapes, chosen by `type`:
+
+- Consent text — **Opt-Out Confirmation** (`OptOutConfirmation`) and **Help Response** (`HelpResponse`): `TextResponse` shape; generate elements with `autoResponseContentType: TextResponse`, `language`, and XML-escaped `response` text.
+- Messaging Components — `MessageDefinition` shape; the referenced `ConversationMessageDefinition` must exist first. If it doesn't, delegate to `conversation-message-definition-builder` to create it, then generate the element with `autoResponseContentType: MessageDefinition` and `messageDefinitionName` (no `language`, no `response`):
+  - **Conversation Acknowledgement** (`InitialResponse`), **Start Conversation** (`AgentEngagedResponse`), **End Conversation** (`AgentEndEngagementResponse`), **Inactive Conversation** (`EndUserInactiveResponse`), **Reroute Conversation** (`RerouteResponse`), **Routing Unavailable** (`RoutingUnavailableResponse`).
+  - **Warning Message** (`EndUserIdleResponse`) — the idle warning; ask "How many minutes before the session inactivates/ends should the warning show?" (Setup: "Minutes to Show Warning"; `responseTimeoutInMins`, 4-30, less than `endUserIdleTimeOut`). `responseTimeoutInMins` is allowed only on `EndUserIdleResponse` and `EndUserInactiveResponse`.
+
+Offer **every** type above (nine in all), never a subset. A question tool that allows only four options means asking in several rounds; do not merge types into buckets or drop any. If the user says only "automated responses", ask round by round until each type is accepted or declined. Ask for the `TextResponse` wording (Opt-Out, Help) instead of inventing it. Create any missing component by **invoking the `conversation-message-definition-builder` skill** (Skill tool) and deploying what it produces. Never write, copy, or adapt a `ConversationMessageDefinition` by hand, including by copying the shape of an existing one: the builder owns the required layout, `AutoResponse` type, and `Title` constant. If the builder skill is not available, stop and tell the user; do not fall back to hand-writing.
+
+When adding to an existing channel, retrieve it first and keep **one** `automatedResponses` block per `type`. A second block of the same type fails the deploy with `duplicate value found: MessagingChannelId`; the cause is the duplicate block, not the component.
+
+Checks:
+- [ ] Every type was offered, and each answer (accepted or declined) was recorded.
+- [ ] `OptOutConfirmation`/`HelpResponse`: `TextResponse` shape with `language` + `response`, special characters XML-escaped.
+- [ ] Every other type: `MessageDefinition` shape with `messageDefinitionName` set and `language`/`response` both absent.
+- [ ] `messageDefinitionName` references a `ConversationMessageDefinition` that already exists in the org (otherwise: "reference not found" — build it with `conversation-message-definition-builder` first).
+- [ ] `responseTimeoutInMins` (4-30) appears only on `EndUserIdleResponse`/`EndUserInactiveResponse`, and on `EndUserIdleResponse` is less than `endUserIdleTimeOut`.