@salesforce/afv-skills 1.61.0 → 1.63.0

package/skills/crm-analytics-wave-generate/scripts/verify_synthetic_dataset.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Post-upload SAQL sanity checks: row count, sum/min/max on numeric fields, group-by-dimension breakdowns.
+// Usage: node scripts/verify_synthetic_dataset.js <alias> <datasetId> <versionId>
+
+const { execSync, execFileSync } = require("child_process");
+
+function getOrgCredentials(alias) {
+  const result = execFileSync('sf', ['org', 'display', '-o', alias, '--json'], { encoding: "utf8" });
+  const json = JSON.parse(result);
+  return { accessToken: json.result.accessToken, instanceUrl: json.result.instanceUrl };
+}
+
+function apiFetch(instanceUrl, accessToken, apiPath, method = "GET", body = null) {
+  const url = `${instanceUrl}${apiPath}`;
+  const args = [
+    "-s",
+    "-H", `Authorization: Bearer ${accessToken}`,
+    "-H", "Content-Type: application/json",
+    "-X", method,
+    "-w", "\\nHTTP_STATUS:%{http_code}",
+  ];
+  if (body !== null) args.push("-d", JSON.stringify(body));
+  args.push(url);
+  const raw = execSync(`curl ${args.map(a => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ")}`, {
+    encoding: "utf8", maxBuffer: 10 * 1024 * 1024,
+  });
+  const parts = raw.split("\nHTTP_STATUS:");
+  const httpStatus = parseInt(parts[1] || "0", 10);
+  if (httpStatus < 200 || httpStatus >= 300) {
+    throw new Error(`HTTP ${httpStatus} on ${method} ${apiPath}: ${parts[0]}`);
+  }
+  return JSON.parse(parts[0]);
+}
+
+function runSaql(instanceUrl, accessToken, datasetId, versionId, saql) {
+  const body = {
+    query: saql,
+    queryLanguage: "SAQL",
+    overrideHeadProcessing: true,
+  };
+  // Substitute dataset id/version for /wave/query
+  const boundQuery = saql.replace(/"__DATASET__"/, `"${datasetId}/${versionId}"`);
+  body.query = boundQuery;
+  return apiFetch(instanceUrl, accessToken, "/services/data/v59.0/wave/query", "POST", body);
+}
+
+const [,, alias, datasetId, versionId] = process.argv;
+if (!alias || !datasetId || !versionId) {
+  console.error("Usage: node verify_synthetic_dataset.js <alias> <datasetId> <versionId>");
+  process.exit(1);
+}
+
+const { accessToken, instanceUrl } = getOrgCredentials(alias);
+
+// Fetch XMD to know field names
+const xmdResult = apiFetch(instanceUrl, accessToken,
+  `/services/data/v59.0/wave/datasets/${datasetId}/versions/${versionId}/xmd`
+);
+const xmd = xmdResult.xmd || xmdResult;
+const measures = (xmd.measures || []).slice(0, 3);
+const dimensions = (xmd.dimensions || []).slice(0, 2);
+
+const results = {};
+
+// Row count
+const countSaql = `q = load "__DATASET__"; q = group q by all; q = foreach q generate count() as count;`;
+const countResult = runSaql(instanceUrl, accessToken, datasetId, versionId, countSaql);
+results.rowCount = countResult.results?.records?.[0]?.count ?? null;
+
+// Sum/min/max for first measure
+if (measures.length > 0) {
+  const m = measures[0].fieldName || measures[0].name;
+  const statSaql = `q = load "__DATASET__"; q = group q by all; q = foreach q generate sum('${m}') as total, min('${m}') as minVal, max('${m}') as maxVal;`;
+  const statResult = runSaql(instanceUrl, accessToken, datasetId, versionId, statSaql);
+  results.measureStats = statResult.results?.records?.[0] || null;
+}
+
+// Group-by for first dimension
+if (dimensions.length > 0) {
+  const d = dimensions[0].fieldName || dimensions[0].name;
+  const groupSaql = `q = load "__DATASET__"; q = group q by '${d}'; q = foreach q generate '${d}' as dim, count() as count; q = limit q 10;`;
+  const groupResult = runSaql(instanceUrl, accessToken, datasetId, versionId, groupSaql);
+  results.dimensionBreakdown = groupResult.results?.records || null;
+}
+
+console.log(JSON.stringify(results, null, 2));

package/skills/service-itsm-agentic-setup-incident-management/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: service-itsm-agentic-setup-incident-management
-description: "Orchestrator for Incident Management setup in Salesforce Service Cloud ITSM: presents the available features, tracks progress, and configures each — SLA & Milestones, Priority Matrix, Incident preferences, Major Incident Management, Incident persona PSG assignment, and Service Management Privilege. Use for: set up or configure incident management, incident management walkthrough, what incident features can I configure; the incident preference toggles (default field validations, auto-close child incidents, auto-triage, assign with Einstein, restrict assigned group, rich text descriptions); Major Incident Management (approval group + MIM preferences); assigning the Incident Fulfiller or Incident Manager persona PSG to a user; Service Management Privilege / privilege escalation setup. DO NOT TRIGGER for: the master on/off switch (service-itsm-incident-mgmt-configure), the Priority Matrix or SLA alone, the Major Incident Manager PSG, creating/editing PSGs, or Problem/Change/Case Management."
+description: "Orchestrator for Incident Management setup in Service Cloud ITSM: presents the features, tracks progress, and configures each — SLA & Milestones, Priority Matrix, Incident preferences, Major Incident Management, Incident persona PSG assignment, Service Management Privilege, and Incident audit tracking. Use for: set up or configure incident management, incident management walkthrough, what incident features can I configure; the incident preference toggles (default field validations, auto-close child incidents, auto-triage, assign with Einstein, restrict assigned group, rich text descriptions); Major Incident Management (approval group + MIM preferences); assigning the Incident Fulfiller or Incident Manager persona PSG; Service Management Privilege / privilege escalation setup. DO NOT TRIGGER for: the master on/off switch (service-itsm-incident-mgmt-configure), the Priority Matrix, SLA, or field history tracking alone, the Major Incident Manager PSG, creating/editing PSGs, or Problem/Change/Case Management."
 metadata:
-  version: "2.0"
+  version: "2.1"
   domains: ["Service"]
   minApiVersion: "67.0"
   relatedSkills:
@@ -16,11 +16,7 @@ metadata:
     headless-360:
       tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
       semver: ">=1.0.0"
-  accessCheck:
-    - type: "userPerm"
-      value: "CustomizeApplication"
-    - type: "orgPerm"
-      value: "IncidentMgmt.orgHasITSMOrgPermission"
+  accessCheck: "(UserPermissions.CustomizeApplication) && (IncidentMgmt.orgHasITSMOrgPermission)"
 allowed-tools: |
   Read AskUserQuestion
   mcp__headless-360__discover
@@ -32,8 +28,9 @@ allowed-tools: |
 # Incident Management Setup Orchestrator
 
 Guide the user through setting up Incident Management features in Salesforce Service Cloud ITSM by
-presenting the available capabilities, tracking progress, and — per feature — either **delegating** to a
-specialized child skill or **executing the feature inline over its system of record (SOR)**.
+presenting the available capabilities, tracking progress, and — per feature — either **delegating** it (to
+a specialized child skill, or to a Setup Operation Recipe (SOR) whose own steps this skill follows), or
+**executing it inline** from this skill's reference file over its SOR.
 
 ## Goal
 
@@ -51,12 +48,43 @@ until the user is done.
 | 4 | Major Incident Management | **Inline over SOR** → `references/major-incident-management.md` |
 | 5 | Incident Persona PSG | **Inline over SOR** → `references/incident-persona-psg.md` |
 | 6 | Service Management Privilege | **Inline over SOR** → `references/service-mgmt-privilege.md` |
-
-**Delegated** features invoke their child skill (this skill only coordinates). **Inline** features are run
-by this skill directly through the `headless-360` MCP server — **read the matching reference file before
-executing that feature** and follow it. Every inline operation is fetched at runtime: `discover` by intent,
-`describe` for the current route/schema/labels, then `dispatch_readonly` (reads) / `dispatch` (writes).
-**Hardcode nothing — `describe` wins.**
+| 7 | Audit Tracking | **Delegate** → `FieldHistoryTracking` (the Field History Tracking SOR) |
+
+**Delegated** features hand off to their child skill or SOR. A child skill runs its own confirmations and
+read-backs, so this skill only coordinates. A SOR is a recipe, not an agent: for a SOR hand-off this skill
+runs the SOR's steps itself and owns the confirmation and read-back (see Audit Tracking below).
+**Inline** features are run by this skill directly through the `headless-360` MCP server — **read the
+matching reference file before executing that feature** and follow it. Every inline operation is fetched at
+runtime: `discover` by intent, `describe` for the current route/schema/labels, then `dispatch_readonly`
+(reads) / `dispatch` (writes). **Hardcode nothing — `describe` wins.**
+
+**Audit Tracking is delegated to the Field History Tracking SOR.** This skill has no reference file for it
+and re-derives none of its steps — the SOR's own steps and guidance decide *how*. This skill runs them and
+owns the user-facing gates:
+
+1. `discover` the SOR by intent (e.g. "field history tracking") and `describe` the id `discover` returns
+   (`FieldHistoryTracking`). Judge availability by what the calls return, not by a step's `status` label —
+   a step labelled `proposed` may still be served. A `discover` miss or a `401`/`403`/`404` means the
+   surface isn't available to this user or org: surface it and stop.
+2. Use the Incident fields the user already named, or ask which fields to track if the choice is missing
+   or ambiguous, plus anything else `describe` says it needs. If the user chooses no fields, leave the
+   feature `Not done` and stop; do not treat an empty choice as already configured.
+3. Through the SOR, check Setup access, read Incident with `get-single-entity-data-with-metadata`, and get
+   its per-object tracked-field limit. Use the returned tracking flag, field labels, `canBeTracked` values,
+   current tracked set, and `fieldEnumOrId` keys to resolve the user's choices; do not guess field keys.
+4. The save replaces the object's whole tracked-field set, so send the **union** of what's already tracked
+   and the chosen fields using their returned keys, with Incident's object-level tracking flag on — never
+   drop an already-tracked field unless the user asks. If a chosen field can't be tracked, or the union
+   would exceed the limit, say so plainly; never untrack another field to make room. Report it as done
+   with no write only if the nonempty chosen set is already tracked **and** Incident's object-level tracking
+   is on. If the fields are selected but that flag is off, the change still needs a save.
+5. Show the exact final tracked-field list by field label (disambiguate matching labels) in either case.
+   Before any save, also show that object-level tracking will be enabled and get an explicit yes
+   (`AskUserQuestion`) for that plan; when the user already named the fields, this confirms the selection.
+6. After any save, read Incident's tracked fields back through the SOR. Mark the feature `Done` only when
+   the live read (for the no-write case) or post-save read-back shows Incident's object-level tracking on,
+   the chosen fields tracked, and no field dropped that the user didn't ask to drop — a save response alone
+   is not proof.
 
 ## Behavior
 
@@ -92,9 +120,11 @@ several enqueue for sequential handling in step 4.
 ### 4. Handle each selected feature in order
 
 Handle selected features sequentially in dependency order (or the order given). For each: if it is a
-**delegated** feature, invoke its child skill; if it is an **inline** feature, **read its reference file**
-and execute it there — always **read live state before writing, confirm before every write, and verify
-every write by read-back**. Honor the per-feature invariants below.
+**delegated** feature, hand off to its child skill — or, for Audit Tracking, run the Field History Tracking
+SOR through the six steps above; if it is an **inline** feature, **read its reference file** and execute it
+there. Whenever this skill itself writes (inline, or a SOR hand-off), always **read live state before
+writing, confirm before every write, and verify every write by read-back**. Honor the per-feature
+invariants below.
 
 ### 5. After each feature completes
 
@@ -110,7 +140,8 @@ template in `examples/output-templates.md`.
 
 ## Critical inline-execution invariants (load-bearing — full detail in each reference)
 
-Apply these whenever an inline feature runs. They are irreversible or silently-wrong if missed.
+Apply these whenever an inline feature runs; the **Everywhere** rules also apply to the Audit Tracking SOR
+hand-off. They are irreversible or silently-wrong if missed.
 
 - **Resolve the right node (Preferences).** Target the ITSM Incident Management org-preferences node
   (controller `IPCManagementSetupController`), **not** the Service-Foundation look-alike
@@ -150,6 +181,7 @@ Apply these whenever an inline feature runs. They are irreversible or silently-w
 4. Major Incident Management   (approval group + two MIM preferences)      [inline]
 5. Incident Persona PSG        (Fulfiller / Manager persona for a user)    [inline]
 6. Service Management Privilege (escalation level + privilege assignments) [inline]
+7. Audit Tracking              (field history on chosen Incident fields)   [delegated]
 ```
 
 ---
@@ -166,6 +198,10 @@ Apply these whenever an inline feature runs. They are irreversible or silently-w
   response — the table is the visual view; the tool call is the selection channel
 - For an **inline** feature, ALWAYS read its reference file first and follow the SOR at runtime — never
   hardcode a route, body, or preference name
+- For **Audit Tracking**, ALWAYS keep every already-tracked Incident field in the save unless the user asked
+  to stop tracking it, confirm the exact final field list before the save, and verify by read-back before
+  marking it `Done` (or verify the already-configured state by live read with no write) — the SOR asks the
+  user nothing itself
 - NEVER set up a feature the user did not select; for "set up everything", walk each feature sequentially
   in recommended order, confirming between each step
 - Track progress across the conversation — do not re-present completed features as "Not done"
@@ -187,7 +223,11 @@ Before emitting any menu or summary, confirm each; adjust the output before send
       sequentially with confirmation under an "all" / "everything" request)
 - [ ] For an inline feature: its reference file was read; live state was read before any write; each write
       was confirmed and verified by read-back; one-way / license-ordering invariants were honored
-- [ ] For a delegated feature: the child skill was invoked, not configured inline
+- [ ] For a delegated feature: the child skill (or, for Audit Tracking, the Field History Tracking SOR) was
+      used, not configured inline
+- [ ] For Audit Tracking: a live metadata read resolved the fields and complete labeled set; any save kept
+      every already-tracked field the user didn't ask to drop, was confirmed before it ran, and was verified
+      by read-back; a no-write `Done` also had Incident's object-level tracking confirmed on
 - [ ] No Salesforce record IDs appear in the output — human-readable names only
 
 ---

package/skills/service-itsm-agentic-setup-incident-management/examples/output-templates.md

@@ -26,6 +26,8 @@ Here are the features available for Incident Management. Select one or more to c
 │   │                               │ persona to a user (bundle + backing licenses)    │          │
 │ 6 │ Service Management Privilege  │ Escalation level, privilege records + employee   │ Not done │
 │   │                               │ assignments, behind Enable Privilege Assignment  │          │
+│ 7 │ Audit Tracking                │ Turn on field history tracking for the Incident  │ Not done │
+│   │                               │ fields you choose (who changed what, and when)   │          │
 └───┴───────────────────────────────┴──────────────────────────────────────────────────┴──────────┘
 
 Reply with the numbers of the features you want to set up (one or more, e.g. `1,3`).
@@ -48,6 +50,7 @@ Incident Preferences — configured successfully
 │ 4 │ Major Incident Management     │ Not done │
 │ 5 │ Incident Persona PSG          │ Not done │
 │ 6 │ Service Management Privilege  │ Not done │
+│ 7 │ Audit Tracking                │ Not done │
 └───┴───────────────────────────────┴──────────┘
 
 Say a number to configure the next feature, or `done` to finish.
@@ -66,7 +69,7 @@ finished — even if some features are still `Not done`. When rendering:
   - All `Done` → `Your Incident Management features are configured.`
   - Otherwise → `You have finished the features you selected. The remaining features can be resumed later by re-invoking this orchestrator.`
 
-Example — user finished with three features configured, three left:
+Example — user finished with three features configured, four left:
 
 ```text
 Incident Management Setup — Finished
@@ -81,6 +84,7 @@ Incident Management Setup — Finished
 │ Major Incident Management     │ Done     │
 │ Incident Persona PSG          │ Not done │
 │ Service Management Privilege  │ Not done │
+│ Audit Tracking                │ Not done │
 └───────────────────────────────┴──────────┘
 
 You have finished the features you selected. The remaining features can be resumed later by re-invoking this orchestrator.

package/skills/service-itsm-agentic-setup-incident-management/references/incident-persona-psg.md

@@ -8,9 +8,9 @@ sets require. This runs **inline** through the Salesforce-hosted **`headless-360
 comes from the OAuth JWT on the MCP session — never handle an org id, alias, or credentials. Minimum API
 version **67.0**.
 
-## Delegate to the systems of record
+## Delegate to the Setup Operation Recipes
 
-Every operation is delegated to a system of record (SOR) and its exact shape is fetched at runtime —
+Every operation is delegated to a Setup Operation Recipe (SOR) and its exact shape is fetched at runtime —
 `discover` by intent, `describe` the SOR step for its **current** route, method, and argument schema, then
 `dispatch_readonly` (reads) / `dispatch` (writes). **Hardcode no routes, SOQL, or request bodies; use what
 `describe` returns, and if it disagrees with anything here, `describe` wins.** Discover by intent, not by

package/skills/service-itsm-agentic-setup-incident-management/references/incident-preferences.md

@@ -9,9 +9,9 @@ on the MCP session — never handle an org id, alias, or credentials. Minimum AP
 This is **not** the master Incident Management on/off switch (`service-itsm-incident-mgmt-configure`) nor
 the Incident Priority Matrix (`service-itsm-incident-priority-configure`).
 
-## Delegate to the system of record
+## Delegate to the Setup Operation Recipe
 
-Every operation is delegated to a system of record (SOR) and its exact shape is fetched at runtime:
+Every operation is delegated to a Setup Operation Recipe (SOR) and its exact shape is fetched at runtime:
 `discover` the operation by intent, `describe` the SOR for its **current** steps, routes, argument schema,
 the preference list, the on-screen labels, and its `agent_guidance`, then `dispatch_readonly` (reads) /
 `dispatch` (writes). **Hardcode no routes, preference names, labels, or request bodies — use what

package/skills/service-itsm-agentic-setup-incident-management/references/major-incident-management.md

@@ -7,12 +7,12 @@ preferences**. This runs **inline** through the Salesforce-hosted
 `dispatch_readonly`, `dispatch`). The org comes from the OAuth JWT on the MCP session — never handle an org
 id, alias, or credentials. Minimum API version **67.0**.
 
-## Delegate every operation to the MIM system of record
+## Delegate every operation to the MIM Setup Operation Recipe
 
-The **Major Incident Management SOR** is the single source of truth for **how** each step is done — the
-route, method, request/response shape, field names, per-step `status`, and `depends_on` ordering. It is
-**actively evolving**, so **never hardcode a route or request body**. Carry only the **goal, scope,
-ordering, and invariants**, and at runtime:
+The **Major Incident Management Setup Operation Recipe (SOR)** is the single source of truth for **how**
+each step is done — the route, method, request/response shape, field names, per-step `status`, and
+`depends_on` ordering. It is **actively evolving**, so **never hardcode a route or request body**. Carry
+only the **goal, scope, ordering, and invariants**, and at runtime:
 
 1. `discover` the operation by intent (e.g. `"set major incident approval group"`, `"validate major
    incident approval group users"`, `"toggle major incident org preference"`).

package/skills/service-itsm-agentic-setup-incident-management/references/service-mgmt-privilege.md

@@ -8,12 +8,12 @@ behind the **Enable Privilege Assignment** master toggle. This runs **inline** t
 `dispatch_readonly`, `dispatch`). The org comes from the OAuth JWT on the MCP session — never handle an org
 id, alias, or credentials. Minimum API version **67.0**.
 
-## Delegate every operation to the system of record
+## Delegate every operation to the Setup Operation Recipe
 
-The **Service Management Privilege setup SOR** is the single source of truth for **how** each step is done —
-the route, method, request/response shape, field names, per-step `status`, and `depends_on`. It is **draft
-and actively evolving**, so **never hardcode a route or request body**. Carry only the **goal, scope,
-ordering, and invariants**, and at runtime:
+The **Service Management Privilege Setup Operation Recipe (SOR)** is the single source of truth for **how**
+each step is done — the route, method, request/response shape, field names, per-step `status`, and
+`depends_on`. It is **draft and actively evolving**, so **never hardcode a route or request body**. Carry
+only the **goal, scope, ordering, and invariants**, and at runtime:
 
 1. `discover` the operation by intent (e.g. `"enable privilege assignment toggle"`, `"set ITSM escalation
    level"`, `"create a service management privilege"`, `"assign employees to a service privilege"`).