forcedotcom/sf-skills / plugins/builder/service-itsm/skills/service-itsm-agentic-setup-itsm-agentforce-permset-assign
service-itsm-agentic-setup-itsm-agentforce-permset-assign
VerifiedResolve missing ITSM Intelligence invocable actions so a Fulfiller NGA agent can activate. Reads which of the three Core Fulfiller persona permsets (IncidentFulfiller, ProblemFulfillerPermSet, ChangeRequestFulfillerPermSet) are provisioned, then assigns the running user the selected persona (plus backing PSL when license-gated) so svc_itsm_intelligence__* actions surface; hands off to service-itsm-agentic-setup-agentforce-studio-validate if none are provisioned. Use when the Fulfiller agent-configure skill reports missing actions on activate, when 'Invocable action svc_itsm_intelligence__X does not exist' surfaces, when a user asks to grant themselves Fulfiller prompt-template access, when asked to assign the Incident, Problem, or Change Fulfiller persona permission set, or when resolving missing ITSM Intelligence action access for the Fulfiller agent. DO NOT TRIGGER for Employee-agent access, Agentforce for IT Service toggles, agent creation, CMDB access, or generic permset assignment.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.2 KB |
| references/cli-invocation.md | markdown | 5.6 KB |
| references/helper-contracts.md | markdown | 7.3 KB |
| references/permset-topology.md | markdown | 3.4 KB |
| scripts/classify-action-surface.mjsexecutable | script | 5.9 KB |
| scripts/classify-assignment-state.mjsexecutable | script | 4.7 KB |
| scripts/classify-permset-availability.mjsexecutable | script | 4.8 KB |
| scripts/resolve-target-user.mjsexecutable | script | 3.0 KB |
references/cli-invocation.md
View on GitHub# CLI Invocation — service-itsm-agentic-setup-itsm-agentforce-permset-assign
Every read and write in this skill uses the **Salesforce CLI (`sf`)** against the CLI's stored session for `--target-org <alias>`. **Never extract the access token** from `sf org display` — hand-building a raw HTTP request bypasses the CLI session and leaks a bearer token into shell context.
## `--json` rule
- `sf data query` **takes** `--json`. Results come back in a `{status, result: {records: [...]}}` envelope — that's what the classifier scripts expect.
- `sf api request rest` does **not** — its raw stdout body is already JSON. Passing `--json` here errors on some Connect endpoints.
- `sf org assign permset` **takes** `--json`. Its `result` field carries `{ successes: [...], failures: [...] }`.
## Discovery read (Phase 1)
Fixed-lookup query over the three Core-shipped Fulfiller persona `PermissionSet.Name` values (see `permset-topology.md`). The namespace on all three is `force` — do NOT filter by `NamespacePrefix`.
```bash
sf data query \
-q "SELECT Id, Name, Label, LicenseId \
FROM PermissionSet \
WHERE Name IN ( \
'IncidentFulfiller', \
'ProblemFulfillerPermSet', \
'ChangeRequestFulfillerPermSet' \
)" \
--target-org <alias> --json
```
Interpret the result:
- **≥1 row** ⇒ Branch A (assign). Ask the user which persona to assign — do NOT auto-select.
- **Zero rows** ⇒ Branch B (hand-off). The ITSM AddOn(s) are not provisioned; route to `service-itsm-agentic-setup-agentforce-studio-validate`.
There is no separate `InstalledSubscriberPackage` or namespace-wide `PermissionSetLicense` query in Phase 1 — the persona lookup above is sufficient because Core AddOn provisioning materializes the persona `PermissionSet` rows directly.
## Identity read (Phase 2a)
```bash
sf api request rest "/services/data/v67.0/" --method GET --target-org <alias>
```
Response `identity` is a URL ending in `/<orgId>/<userId>`. Take the last path segment starting with `005` as the running user Id via `scripts/resolve-target-user.mjs`. Do **not** call `USER_ID()` (Apex-only), `/chatter/users/me`, or `/connect/user-profiles/me` — those either fail against REST or 403 when Chatter/Communities is off.
For a named user, resolve by `Username`:
```bash
sf data query -q "SELECT Id, Username, Name, IsActive FROM User WHERE Username = '<username>'" \
--target-org <alias> --json
```
## Idempotency reads (Phase 2b)
Substitute `<permsetId>` with the SELECTED persona's `Id` and `<pslId>` with the SELECTED persona's `LicenseId` (both from Phase 1's `candidates[]`).
```bash
sf data query -q "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetId = '<permsetId>'" \
--target-org <alias> --json > /tmp/psa-existing.json
# Only when needsPsl:true on the selected persona:
sf data query -q "SELECT Id FROM PermissionSetLicenseAssign WHERE AssigneeId = '<userId>' AND PermissionSetLicenseId = '<pslId>'" \
--target-org <alias> --json > /tmp/psla-existing.json
```
When the selected persona's `needsPsl:false` (its `PermissionSet` has no backing `LicenseId`), SKIP the PSLA query — pass the sentinel `NO-PSL` to `classify-assignment-state.mjs`.
## Writes (Phase 2d)
Assign the PSL first, then the permission set — the license backs the permset, and the assignment is not fully effective until the seat is held. When `needsPsl:false`, skip the PSL POST entirely and only run `sf org assign permset`.
```bash
# PSL first — POST to the sObject endpoint (no bulk API dependency). needsPsl:true only.
sf api request rest "/services/data/v67.0/sobjects/PermissionSetLicenseAssign" \
--method POST \
--body '{"AssigneeId":"<userId>","PermissionSetLicenseId":"<pslId>"}' \
--target-org <alias>
```
Response envelope: `{"id":"0Pk...","success":true,"errors":[]}` on assignment; `[{"errorCode":"DUPLICATE_VALUE",...}]` when the user already holds it (treat as success).
```bash
# Permset — sf CLI subcommand, supports --on-behalf-of for a named user.
# <permsetName> is the selected persona's DeveloperName (from candidates[].Name).
sf org assign permset --name "<permsetName>" \
--on-behalf-of <userId> \
--target-org <alias> --json
```
Response envelope: `result.successes[]` and `result.failures[]`. A `failure.message` matching `Duplicate id` / `already has` is idempotent success.
## Verify read (Phase 4)
```bash
sf api request rest "/services/data/v67.0/actions/custom/generatePromptResponse" \
--method GET --target-org <alias>
```
Response can be either `{actions: [ {name, ...}, ... ]}` (legacy) or `{actions: {<name>: {...}, ...}}` (newer). The Fulfiller agent-configure skill's Phase 1b provides the specific `svc_itsm_intelligence__*` names to look for; passed as the second arg to `classify-action-surface.mjs`.
## Common error responses (surface verbatim)
| Status / errorCode | Meaning | Handling |
|---|---|---|
| `400 DUPLICATE_VALUE` on PSL POST | User already holds this PSL | Idempotent success; not a failure |
| `400 INSUFFICIENT_ACCESS` on PSL POST | PSL seat exhausted | STOP the write; tell the user how many seats are in use vs licensed |
| `401 Unauthorized` on any call | CLI session expired for the target alias | `sf org login web --alias <alias>` and retry |
| `403 FUNCTIONALITY_NOT_ENABLED` on the verify GET | The `generatePromptResponse` custom-action endpoint is gated on this user | Same signal as Branch A but for the discovery route — surface it and check whether the assigned persona permset actually gates the target actions |
| `404 Not Found` on `sf org assign permset` | Permset name does not exist on this org | Re-run Phase 1 discovery; the org state may have changed |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |