@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/service-email-to-case-configure/examples/CaseSettings-two-addresses.settings-meta.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Example: Email-to-Case enabled with two routing addresses (EmailToCase + Outlook).
+  This is the source-file shape that apply-casesettings.py consumes.
+
+  Note what is and is NOT here:
+    1. The two required emailToCase switches (enableEmailToCase + enableOnDemandEmailToCase)
+       and, on each address, the required addressType / routingName / caseOrigin / casePriority.
+    2. NO emailAddress on either address. The customer-facing emails are supplied at apply
+       time via one routing-email option per address, in this document order (first the
+       Support Inbox email, then the Sales Outlook Inbox email). See SKILL.md step 9.
+    3. Support Settings (Default Case Owner / Automated Case User) appear here only when the
+       user names them — this example names none, so none are set. When named, write the
+       paired fields (defaultCaseOwner + defaultCaseOwnerType, etc.); fields the org already
+       has are preserved when omitted. Never defaulted to the authenticated user.
+-->
+<CaseSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <emailToCase>
+        <enableEmailToCase>true</enableEmailToCase>
+        <enableOnDemandEmailToCase>true</enableOnDemandEmailToCase>
+        <routingAddresses>
+            <addressType>EmailToCase</addressType>
+            <routingName>Support Inbox</routingName>
+            <caseOrigin>Email</caseOrigin>
+            <casePriority>Medium</casePriority>
+            <createTask>false</createTask>
+            <saveEmailHeaders>true</saveEmailHeaders>
+        </routingAddresses>
+        <routingAddresses>
+            <addressType>Outlook</addressType>
+            <routingName>Sales Outlook Inbox</routingName>
+            <caseOrigin>Email</caseOrigin>
+            <casePriority>High</casePriority>
+        </routingAddresses>
+    </emailToCase>
+</CaseSettings>

package/skills/service-email-to-case-configure/references/apply-mechanics.md

@@ -0,0 +1,73 @@
+# Email-to-Case Apply Mechanics (why the write is shaped this way)
+
+Load-bearing design rationale behind `apply-casesettings.py`. Read this before changing
+how the script builds or sequences its `updateMetadata` payloads. Do not substitute a
+plain deploy or a minimal patch.
+
+## Why two phases (and not a single file-based deploy)
+
+Enabling On-Demand Email-to-Case provisions the org's internal email-service
+infrastructure, and a routing address can only bind to that infrastructure in a
+**subsequent** operation. A single file-based deploy (`sf project deploy`) that both
+enables On-Demand and declares a routing address **fails on a freshly-configured org** —
+verified on clean orgs. `apply-casesettings.py` therefore reads current settings, applies
+the **complete `emailToCase` block** (toggles) plus Support Settings in one `updateMetadata`
+call (Phase A), then re-reads and appends routing addresses in a second call (Phase B).
+
+## Two load-bearing properties of the write
+
+- **Send the whole `emailToCase` block, not a minimal patch.** Provisioning the On-Demand
+  email service is driven by writing the full `emailToCase` block. A minimal field-level
+  patch that just flips `enableOnDemandEmailToCase` to `true` does **not** trigger
+  provisioning, so Phase B then fails with "We couldn't save your routing address... custom
+  email services named EmailToCase." (Verified from scratch on a clean org.)
+- **Send only the top-level fields this skill owns; strip the rest.** The platform
+  re-validates any top-level `CaseSettings` field present in the payload, even at an
+  unchanged value — and several (notably Case Feed) carry dependencies unrelated to
+  Email-to-Case (Case Feed re-validation requires Chatter). `apply-casesettings.py` writes
+  only the fields it sets (`emailToCase`, `enableDraftEmails`, and Support Settings) and
+  drops every other top-level field, which keeps its current org value via field-level
+  merge. This is why the skill needs **no Chatter prerequisite** and does not fail on
+  unrelated org Case configuration. (Verified from scratch on a Chatter-off org: stripping
+  all other top-level fields still provisioned and bound a routing address, and the omitted
+  fields — e.g. `enableCaseFeed` — kept their values.)
+
+This is the validated mechanism; do not substitute a plain deploy, do not reduce the
+`emailToCase` write to a minimal patch, and do not echo the full record back verbatim.
+
+## Support Settings are preserved per field, via field-level merge
+
+Default Case Owner (`defaultCaseOwner` / `defaultCaseOwnerType`) and Automated Case User
+(`defaultCaseUser` / `useSystemUserAsDefaultCaseUser`) are **independent** top-level
+`CaseSettings` fields — an org can have one configured and the other not. Because top-level
+fields merge at the field level (an omitted field keeps its current org value), the script
+**preserves a configured field by simply not emitting it** in the payload, and writes only
+the field(s) that are unset (or that the caller explicitly overwrites with
+`--overwrite-support-settings`). It therefore requires — and validates — input **only** for
+the field being written; supplying a value for an already-configured field without the
+overwrite flag leaves the existing value untouched. This is why a single "both configured?"
+gate is wrong: on a partially-configured org it would either demand the already-set value or
+silently overwrite it. `apply_support_settings` branches the owner and automated-user fields
+separately for exactly this reason.
+
+## Routing-address ordering (multi-address preservation)
+
+The `updateMetadata` call **replaces the `routingAddresses` collection wholesale**.
+An already-provisioned address is **dropped** if a brand-new address follows it in
+document order. Therefore the script **emits new addresses before** the carried-over
+existing ones, so existing addresses always survive.
+
+The platform-managed read-only fields (`emailServicesAddress` / `isVerified`) do **not**
+affect this — only document order does. As defensive hygiene the script still strips those
+read-only fields from the payload (the platform mints them), but stripping is not the
+preservation mechanism; ordering is. A runtime **preservation guard** baselines the
+expected address count (`initial address count + created count`) captured before Phase A and
+**fails the run loudly** if any existing address is dropped anyway.
+
+## API version derivation
+
+The Metadata API version is `max(org apiVersion, 67.0)` — derived from the org and floored
+at the skill's `minApiVersion` (`67.0`). This keeps every field the skill sets valid while
+auto-adopting newer org features (e.g. a v68+ org that supports the `botEmailDefinition`
+binding for Agentforce for Service on Email is picked up automatically). It never claims a
+version the org doesn't report. `--api-version` forces a specific value.

package/skills/service-email-to-case-configure/references/routing_address_reference.md

@@ -0,0 +1,73 @@
+# EmailToCaseRoutingAddress — Field & Surface Reference
+
+Each routing address is one `<routingAddresses>` element inside `CaseSettings.emailToCase`.
+
+## Prerequisites (before routing addresses can be created)
+
+`apply-casesettings.py` applies these in Phase A, before adding any routing address in Phase B. The two `emailToCase` switches are required. On-Demand Email-to-Case requires a Default Case Owner and an Automated Case User to be set: write the values the user names into the source file (the scored, versionable artifact); the script also accepts them as flags and preserves any the org already has (see below).
+
+| Field | Level | Notes |
+|-------|-------|-------|
+| `defaultCaseOwner` | `CaseSettings` | Fallback owner for cases assignment rules can't route. **Preserved if the org already has it.** When not configured, the script requires an explicit, org-validated value: a Username (`defaultCaseOwnerType=User`) or a Queue DeveloperName (`defaultCaseOwnerType=Queue`). Never assumed. |
+| `defaultCaseOwnerType` | `CaseSettings` | `User` or `Queue`. Selects how `defaultCaseOwner` is resolved (Username vs Queue DeveloperName). No silent default — supplied with the owner value. |
+| `defaultCaseUser` | `CaseSettings` | The **Automated Case User** recorded in Case History for automated Email-to-Case changes. A specific active Username. Mutually exclusive with `useSystemUserAsDefaultCaseUser`. |
+| `useSystemUserAsDefaultCaseUser` | `CaseSettings` | Set `true` to use the org's **System** (automated process) user as the Automated Case User instead of a named user. Do **not** also set `defaultCaseUser` (platform error). API 67.0+. |
+| `systemUserEmail` | `CaseSettings` | Email for the automated process user, required with `useSystemUserAsDefaultCaseUser=true` only when the org's automated case user doesn't exist yet. |
+| `enableEmailToCase` | `emailToCase` | Master switch. Cannot be disabled once enabled. |
+| `enableOnDemandEmailToCase` | `emailToCase` | Must be `true` before the org accepts routing addresses. Requires the Default Case Owner + Automated Case User above. |
+
+**Support-settings resolution (Phase A).** The script reads current settings first. If the Default Case Owner or Automated Case User is already configured in the org, it is **preserved** untouched (pass `--overwrite-support-settings` to replace it). For a field the user names, write the value into the source file — `defaultCaseOwner` + `defaultCaseOwnerType`; `defaultCaseUser`, or `useSystemUserAsDefaultCaseUser` (+ optional `systemUserEmail`) — since the file is the scored, versionable artifact; the script also accepts the same values as flags (`--owner-type`/`--owner-value`, `--automated-type`/`--automated-value`, `--system-user-email`). Each value is validated against the org — an unknown user or queue, or an invalid type, fails the run with an actionable message so the caller can re-prompt. For a field that is unset **and** unnamed, ask; the authenticated CLI user is used **only** with `--use-authenticated-user`.
+
+## Surface selection by `addressType`
+
+`addressType` is the gating decision — it determines whether the address can be created via the Metadata API at all.
+
+| `addressType` | Surface | Notes |
+|---------------|---------|-------|
+| `EmailToCase` | **Metadata API** | The standard case. Requires out-of-band verification of the Salesforce-generated forwarding address before it receives production mail. |
+| `Outlook` | **Metadata API** | Used with Salesforce for Outlook. Requires On-Demand Email-to-Case enabled. |
+| `GmailOAuth` | **Metadata API** | Gmail connector. Only one GmailOAuth connector is supported — do not stack a second. |
+| `E2cEasy` | **Service Easy Setup wizard ONLY** | The wizard binds the address to the prebuilt `service_case` queue and completes email round-trip verification. Neither the queue binding nor `isVerified` can be reproduced by a Metadata API deploy. Do not emit Metadata for this type. |
+
+## Writable fields
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `addressType` | enum | Required. One of `EmailToCase`, `Outlook`, `GmailOAuth` (see surface table for `E2cEasy`). |
+| `routingName` | string | Required. Unique label for the routing address. The platform rewrites this to equal the email address for `EmailToCase` addresses. |
+| `caseOrigin` | string | **Required.** Default Case Origin for cases from this address. The operation fails with "Missing caseOrigin" if omitted. |
+| `casePriority` | string | **Required.** Default Case Priority. The operation fails with "Missing casePriority" if omitted. |
+| `caseOwner` | string | **Optional, opt-in per address.** Default owner for cases from this address — an active Username or a Queue DeveloperName. Omit it (the default) to fall back to the org Default Case Owner / assignment rules; set it only when the user chooses a specific owner for this address. **Must** be paired with `caseOwnerType` — the platform rejects `caseOwner` without it. `apply-casesettings.py` validates the value against the org (active user / real queue) and fails closed if it doesn't exist. |
+| `caseOwnerType` | string | `User` or `Queue` — how `caseOwner` is resolved (Username vs Queue DeveloperName). Required whenever `caseOwner` is set; not written on its own. |
+| `createTask` | boolean | If `true`, a task is auto-assigned to the case owner on case creation. |
+| `taskStatus` | string | Default status for the auto-created task. Applies only when `createTask` is `true`. |
+| `authorizedSenders` | string | Comma-separated addresses/domains allowed to submit email (On-Demand E2C). |
+| `saveEmailHeaders` | boolean | Whether routing/envelope headers are saved. |
+| `newEntityRecordType` | string | Case Record Type for cases from this address; defaults to the org's default Case Record Type. Must exist and be active on Case. |
+| `routingFlow` | string | Omni-Channel flow that routes generated cases (API 56.0+). |
+| `fallbackQueue` | string | Queue used when the Omni-Channel flow can't route; must use Case as the service channel object (API 56.0+). |
+| `isPermsetControlled` | boolean | If `true`, only users granted access via a permission set can use the address (API 61.0+). |
+
+## Supplied at apply time — never in the source file
+
+| Field | Why |
+|-------|-----|
+| `emailAddress` | The customer-facing address that routes email into cases. Supplied via `--routing-email` (one per address, in document order), never written in the source file — this keeps the address explicit user input and out of a reusable artifact. The validator rejects a source file that sets it. |
+
+## Read-only fields — never write values for these
+
+| Field | Why |
+|-------|-----|
+| `emailServicesAddress` | Salesforce-generated forwarding address. Read-only; set by the platform. |
+| `isVerified` | Set by the customer's verification flow (clicking the confirmation email). Read-only; cannot be flipped by an apply. |
+
+## Optional org-level `emailToCase` toggles
+
+Set these only when the user asks. `enableEmailToCase` and `enableOnDemandEmailToCase` are the required ones (see Prerequisites).
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `enableHtmlEmail` | boolean | Enables HTML email. |
+| `enableE2CSourceTracking` | boolean | Sets Case Source to Email for E2C-originated cases. |
+| `overEmailLimitAction` | enum | `Bounce` \| `Discard` \| `Requeue` — action when the daily E2C limit is exceeded. |
+| `unauthorizedSenderAction` | enum | `Bounce` \| `Discard` — action for email from invalid senders. |

package/skills/service-email-to-case-configure/references/troubleshooting.md

@@ -0,0 +1,25 @@
+# Email-to-Case — Troubleshooting
+
+Full symptom → resolution table for `apply-casesettings.py`. Read this when the apply
+or verify step reports an error, or when configured settings don't behave as expected.
+
+| Issue | Resolution |
+|-------|------------|
+| Routing address fails on a fresh org with a single deploy | Use `apply-casesettings.py` — it enables the toggles (Phase A) before adding addresses (Phase B). A plain `sf project deploy` cannot provision addresses from scratch. |
+| Phase B fails: "We couldn't save your routing address... custom email services named EmailToCase" | The On-Demand email service was not provisioned. This happens if the On-Demand toggle was set with a minimal field-level patch instead of writing the complete `emailToCase` block. `apply-casesettings.py` writes the full `emailToCase` block in Phase A specifically to provision it; do not reduce the write to a minimal patch. |
+| Apply fails: "The setup requirements for Case Feed Items has to be enabled" | Only happens if the payload includes top-level Case Feed fields (`enableCaseFeed` etc.), which the platform re-validates against Chatter. `apply-casesettings.py` strips all top-level fields it does not own, so it should never hit this. If you see it, confirm the script's `KEEP_TOP_LEVEL_FIELDS` set hasn't been widened to include Case Feed fields. |
+| `--routing-email` count doesn't match the addresses | The script exits non-zero without writing. Provide exactly one `--routing-email` per routing address, in the order they appear in the source file. |
+| Platform rewrites `routingName` to equal `emailAddress` | Expected for `EmailToCase` addresses. The verify read will show `routingName` == the supplied email; this is the platform's behavior, not an error. |
+| Apply fails: "not an active User" / "not a Queue" / "not valid" for owner or automated user | The value the user supplied doesn't exist in the org (or the type is wrong). This is intentional fail-closed behavior — tell the user the value is invalid, ask for a valid Username / Queue DeveloperName / type, and re-run. Do not substitute the authenticated user. |
+| Apply/validate fails: "caseOwner is still the placeholder" or "sets caseOwner without caseOwnerType" on a routing address | A per-address Default Case Owner was left half-filled. Either supply a real value **and** its `caseOwnerType` (`User`/`Queue`), or remove both `caseOwner` and `caseOwnerType` from that address to fall back to the org Default Case Owner. The per-address owner is opt-in — omit it unless the user asked for a specific owner. |
+| Support settings unexpectedly unchanged | The org already had a Default Case Owner + Automated Case User, so they were preserved (`supportSettings.action: preserved-existing`). Pass `--overwrite-support-settings` only if the user explicitly wants to replace them. |
+| Requested address is `GmailOAuth` but org already has one | `GmailOAuth` connectors conflict; do not stack a second. Confirm the existing connector before adding. |
+| `E2cEasy` requested via Metadata | Not supported by the Metadata API — direct the user to the Service Easy Setup wizard. |
+| New address doesn't receive production mail | For `EmailToCase`, the customer must verify the Salesforce-generated forwarding address out-of-band; `isVerified` is read-only and set by that flow, not by the apply. |
+| Org not authenticated / token expired | The script reuses the sf CLI session. Have the user run `sf org login web -a <alias>` (or re-auth) first. |
+| Apply exits: "Target org appears to be PRODUCTION" | The safety gate fired. Confirm with the user that they intend to configure Email-to-Case on this production org (it's permanent), then re-run with `--confirm-production`. Do not add the flag without asking. |
+| Apply exits: "Could not determine whether this is a production org" | The `Organization` row wasn't readable, so the gate fails closed and treats the org as production. Confirm the org is safe to mutate, then re-run with `--confirm-production`. |
+| `--verify-cases` exits non-zero: "No Cases with Origin='Email'" | The inbound test email hasn't been processed yet, the routing address isn't verified, or `--supplied-email` excludes it. The check looks back over `LAST_N_DAYS:3`, so a test email older than that window won't match — send a fresh one. Confirm the user actually sent the email, wait a moment, and re-run. Drop `--supplied-email` if it over-narrows. |
+| `--verify-cases` finds a Case but no incoming `EmailMessage` | The Case may have been created another way (not inbound email). Re-run once the inbound email has been processed; proof requires `Incoming=true` linked to the Case. |
+| "Enable Email Drafts" toggle silently ignored | The element name is `enableDraftEmails` (plural) and lives at the **top level** of `CaseSettings`, not inside `emailToCase`. A singular name or wrong container is ignored by the platform. |
+| An `emailToCase` toggle doesn't take effect | Confirm it belongs in the `emailToCase` section, not top-level. `enableHtmlEmail`, `notifyOwnerOnNewCaseEmail`, `enableE2CDeduplicateAttachments`, and `showWordCountInComposer` are all `emailToCase` children; check the `verified.emailToCase.<field>` value in the JSON summary. |