Skip to content

forcedotcom/sf-skills / skills/service-itsm-incident-priority-configure

service-itsm-incident-priority-configure

Flagged

Configures the Incident Priority Matrix for Salesforce ITSM through the sf CLI — enabling or disabling the matrix, shaping the Impact x Urgency grid that derives Priority on Incident records, toggling the manual-override preference, and reading or setting the default fallback priority. Reads every value before writing, is idempotent, and requires explicit user confirmation before any mutation. Use when the user wants to view, enable, disable, set up, seed, add to, change, or remove priority matrix configuration for Incident records, change the default incident priority, or asks about incident priority setup, impact/urgency mapping, override, or the ITSM incident priority matrix. DO NOT TRIGGER for Problem or ChangeRequest priority matrices, Case priority fields, standard Priority picklists outside ITSM, SLA or milestone configuration, or enabling Incident Management itself (use the service-itsm-incident-mgmt-configure skill).

FileKindSize
SKILL.mdskill md22.2 KB
examples/matrix-operations.mdmarkdown9.4 KB
examples/render-matrix.mdmarkdown2.2 KB
examples/seed-full-matrix.mdmarkdown3.5 KB
references/sf-cli-invocation.mdmarkdown16.1 KB

references/sf-cli-invocation.md

View on GitHub
# sf CLI invocation reference — service-itsm-incident-priority-configure

This skill invokes every read and write through the **`sf` CLI**. Two transports are used:

- `sf api request rest` — direct authenticated REST call against the org.
- `sf data query --use-tooling-api` / `sf data delete record --use-tooling-api` — Tooling API convenience wrappers with better parsing than raw REST.
- `sf project retrieve start` + `sf project deploy start` — for the `StandardValueSet` metadata that carries the default fallback priority.

Every invocation below reflects the exact request and response shapes returned by the platform. Path prefixes are load-bearing; do not strip `/services/data/v67.0/` or `/services/data/v67.0/tooling/`.

## Authentication

`sf` mints the bearer token from the CLI's authenticated org — the skill never handles tokens. Confirm the target org first:

```bash
sf org list
sf org display --target-org <alias>
```

If the org is not `Connected`, run `sf org login web --alias <alias>` (or the JWT equivalent) and re-verify. Every command below takes `--target-org <alias>`.

## Response envelope

`sf api request rest` outputs the raw HTTP body (append `--include` to see the status line + headers). Tooling REST GETs return standard `{records: [...], size: N, totalSize: N, done: true, ...}`. PATCH on the two Setup Connect API prefs returns `{"isPreferenceEnabled": <bool>}` — the new state is echoed, so no re-read is needed.

`sf data query` normalizes Tooling SOQL results into a table by default; add `--json` for a machine-parseable envelope.

---

## Routes

### 1. Preflight — Incident describe (`sf api request rest`)

```bash
sf api request rest \
  "/services/data/v67.0/sobjects/Incident/describe" \
  --method GET \
  --target-org <alias>
```

**Expected:** HTTP 200. Body carries the entity schema. Extract active picklist values for `Impact`, `Urgency`, `Priority` from the `fields[]` array — each field has `picklistValues[]` and each entry has `value` (API name), `label`, and `active` (only `true` counts). Use `value`, not `label` — customers rename labels but the server stores API values.

If the describe response is very large (>1MB), dispatch a subagent (haiku tier) to pull just the three picklists.

If the response is a `404 NOT_FOUND`, Incident Management is not enabled on the org. Direct the user to enable it first (use the `service-itsm-incident-mgmt-configure` skill).

### 2. Matrix enable flag — `IncPriorityMatrixEnabled`

**Read:**

```bash
sf api request rest \
  "/services/data/v67.0/setup/org/preferences/IncPriorityMatrixEnabled" \
  --method GET \
  --target-org <alias>
```

Response: `{"isPreferenceEnabled": <bool>}` — 200.

**Write:**

```bash
sf api request rest \
  "/services/data/v67.0/setup/org/preferences/IncPriorityMatrixEnabled" \
  --method PATCH \
  --header "Content-Type:application/json" \
  --body '{"desiredState": true}' \
  --target-org <alias>
# use '{"desiredState": false}' to disable
```

Response: `{"isPreferenceEnabled": <bool>}` — 200. **The response echoes the new state**, so no re-read is required.

Disabling stops the server from deriving Priority on future Incident writes. Matrix rows and the default priority are **not** cleared; re-enabling restores derivation instantly. Existing Incidents keep their stamped priority.

### 3. Manual override — `IncPriorityOverrideEnabled`

Same shape as `IncPriorityMatrixEnabled` — same URL path except the pref name changes. Read/write via `sf api request rest`, same body shape, same response.

The override flag controls whether users can override the derived priority on an individual Incident record. Flipping it does **not** touch matrix rows or the default priority.

### 4. Matrix rows — read

```bash
sf data query \
  --use-tooling-api \
  --target-org <alias> \
  --query "SELECT Id, DeveloperName, ReferenceObject, Urgency, Impact, Priority FROM ServiceOpPriorityConfig WHERE ReferenceObject = 'Incident'"
```

Zero to `|Impact| × |Urgency|` rows returned. Row keys are PascalCase (`Id`, `DeveloperName`, `ReferenceObject`, `Urgency`, `Impact`, `Priority`) — these are Tooling SObject field names. `DeveloperName` is included so the add step can derive a fresh unique suffix from existing rows.

For programmatic scripts, add `--json` and parse `result.records[]`.

### 5. Matrix rows — add

```bash
sf api request rest \
  "/services/data/v67.0/tooling/sobjects/ServiceOpPriorityConfig" \
  --method POST \
  --header "Content-Type:application/json" \
  --body '{"ReferenceObject": "Incident", "Urgency": "<one of the fetched Urgency values>", "Impact": "<one of the fetched Impact values>", "Priority": "<one of the fetched Priority values>", "DeveloperName": "ServiceOpPriorityConfigIncident<unique-suffix>", "MasterLabel": "ServiceOpPriorityConfigIncident<same-suffix>"}' \
  --target-org <alias>
```

Pass the body inline with `--body '{...}'`. `sf api request rest` accepts either inline JSON or `--body @file`; inline keeps the payload in the skill's control and avoids writing to a path outside the project.

Response: `{"id": "<Id>", "success": true, "errors": [], "warnings": [], "infos": []}` — 201.

Suffix pattern: pattern-match the existing rows' `DeveloperName` values from the Phase-2 read and pick a fresh integer that isn't already used. `DeveloperName` uniqueness is enforced by the Tooling API.

**Important:** The Tooling REST endpoint does NOT enforce picklist validation on `Urgency`, `Impact`, `Priority`. Garbage values are accepted at the wire level but the runtime matrix evaluator refuses to use them. Validate every value against the Phase-1 picklist values before dispatch.

**Duplicates:** the server does NOT enforce `(ReferenceObject, Urgency, Impact)` uniqueness — a second POST on the same coordinate is accepted as a separate row (for example, two rows with identical `(Incident, Medium, High)` coordinates will both persist with distinct `Id`s). Client-side dedup against the Phase-2 snapshot is the ONLY guard against duplicate matrix cells; if you skip it, the runtime picks one of the duplicates non-deterministically.

**ReferenceObject:** the server accepts any string for `ReferenceObject` (for example, a `Problem` row can be inserted successfully). `ServiceOpPriorityConfig` is the shared SObject for Incident / Problem / ChangeRequest matrices. Scope to `Incident` is skill-enforced only — refuse any other value client-side.

### 6. Matrix rows — change

```bash
sf api request rest \
  "/services/data/v67.0/tooling/sobjects/ServiceOpPriorityConfig/<Id>" \
  --method PATCH \
  --header "Content-Type:application/json" \
  --body '{"Priority": "<new value>"}' \
  --target-org <alias>
```

Response: 204 No Content. Look up `<Id>` from the Phase-2 SOQL results by matching `(ReferenceObject=Incident, Urgency, Impact)`.

**Duplicate coordinates:** if more than one Phase-2 row matches the coordinate (the server does not enforce uniqueness), do NOT dispatch the PATCH — the choice of `<Id>` would be non-deterministic. Report all matching rows (`Id`, `DeveloperName`, current `Priority`) and require the user to name the exact `Id` to change or approve a consolidation plan (delete the extras, then change the survivor).

Validate the new Priority against the Phase-1 picklist values.

### 7. Matrix rows — remove

```bash
sf data delete record \
  --sobject ServiceOpPriorityConfig \
  --record-id <Id> \
  --use-tooling-api \
  --target-org <alias>
```

Response: `Successfully deleted record: <Id>`. Look up `<Id>` from the Phase-2 SOQL results by matching `(ReferenceObject=Incident, Urgency, Impact)`.

**Duplicate coordinates:** if more than one Phase-2 row matches the coordinate, do NOT dispatch — deleting an arbitrary duplicate leaves the matrix non-deterministic. Report all matching rows (`Id`, `DeveloperName`, current `Priority`) and require the user to name the exact `Id`(s) to delete or explicitly confirm "delete all rows at this coordinate".

**Note:** `sf api request rest ... --method DELETE` on a Tooling SObject currently fails with `SfError: No 'mode' found in 'body' entry` in `sf` CLI 2.143. Use `sf data delete record` instead.

### 8. Default fallback priority — read

```bash
sf api request rest \
  "/services/data/v67.0/tooling/query/?q=SELECT+Id,MasterLabel,Metadata+FROM+StandardValueSet+WHERE+MasterLabel='IncidentPriority'" \
  --method GET \
  --target-org <alias>
```

Response: 200 with `records[0].Metadata.standardValue[]`. Find the entry with `"default": true` — its `valueName` is the current fallback priority. Every other entry has `"default": false`.

### 9. Default fallback priority — write

Editing `default: true` on a `StandardValueSet` is a metadata operation — the Tooling REST PATCH on `StandardValueSet/<Id>` returns `FIELD_INTEGRITY_EXCEPTION: Unable to load specified entity`. The canonical `sf` CLI path is metadata deploy.

```bash
# Prepare a scratch project (only needed once per session).
# The force-app/main/default/ path is dictated by packageDirectories[0].path in
# sfdx-project.json below — sf project retrieve start writes the metadata there
# by convention, not by user choice.
WORKDIR=$(mktemp -d)
mkdir -p "$WORKDIR/force-app/main/default/standardValueSets"
cat > "$WORKDIR/sfdx-project.json" <<'EOF'
{
  "packageDirectories": [{"path":"force-app","default":true}],
  "namespace": "",
  "sfdcLoginUrl": "https://test.salesforce.com",
  "sourceApiVersion": "67.0"
}
EOF

# Step 1: retrieve current StandardValueSet
cd "$WORKDIR" && sf project retrieve start \
  --metadata "StandardValueSet:IncidentPriority" \
  --target-org <alias>

# Step 2: edit the XML to set <default>true</default> on the new default
#         and <default>false</default> on every other value.

# Step 3: deploy the modified file
sf project deploy start \
  --metadata "StandardValueSet:IncidentPriority" \
  --target-org <alias> \
  --wait 10
```

**Expected:** `Status: Succeeded` in the deploy output. On failure, report the raw deploy output verbatim.

The XML shape is:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <sorted>false</sorted>
    <standardValue>
        <fullName>Critical</fullName>
        <default>false</default>
        <label>Critical</label>
    </standardValue>
    <standardValue>
        <fullName>High</fullName>
        <default>true</default>
        <label>High</label>
    </standardValue>
    <!-- ... one <standardValue> block per active picklist value ... -->
</StandardValueSet>
```

Exactly one `<default>true</default>` should be present at deploy time.

### 10. Salesforce Go setup-step completion — write (after a mutation only)

The "Define Priority Matrix" tile in the Salesforce Go setup checklist (feature
`service-cloud-itsm-incident`, step `definePriorityMatrix`) is a **user-override** step: its
"Done" checkmark is a user-supplied `StepProgress` record, **not** derived from org state.
Writing the matrix config (prefs, rows, default) functionally is invisible to the checklist —
the completion must be written explicitly, exactly as the guided modal does on save.

```bash
sf api request rest \
  "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-incident/configuration/step/definePriorityMatrix/progress" \
  --method PUT \
  --header "Content-Type:application/json" \
  --body '{"isComplete": true}' \
  --target-org <alias>
```

**Expected:** HTTP 200 with the updated progress. The endpoint is idempotent — re-asserting
`isComplete: true` when already complete is a harmless 200, so no read-before-write is needed.

- **`isComplete` is REQUIRED.** Omitting it returns **HTTP 500** (server-side NPE), not a 400.
- **Fire only after a functional Phase-4 write has landed** (a pref PATCH, a row POST/PATCH/delete,
  or a `StandardValueSet` deploy). On a view-only read or an idempotent no-op, dispatch **nothing** —
  there is no configuration action to mark done, and the completion PUT is itself a mutation.
- This is the same feature the master-pref preflight reads via `/connect/setup/discovery/features`
  (filter `apiName == "service-cloud-itsm-incident"`); here the singular `.../feature/service-cloud-itsm-incident/...`
  subresource carries the per-step progress.
- Rely on the 200 success signal. Any non-200 surfaces verbatim through the skill's standard error
  handling — the completion PUT is not special-cased.

---

## Idempotency contract

| Concern | Match rule (skip the write when …) |
|---------|-------------------------------------|
| `IncPriorityMatrixEnabled` | Phase-2 `isPreferenceEnabled` already equals the requested boolean |
| `IncPriorityOverrideEnabled` | Phase-2 `isPreferenceEnabled` already equals the requested boolean |
| Add a cell | A Phase-2 row already matches `(ReferenceObject, Urgency, Impact)` — even if its Priority differs (surface the mismatch and ask; add is not a change) |
| Change a cell | The Phase-2 row's `Priority` already equals the requested value |
| Remove a cell | No Phase-2 row matches `(ReferenceObject, Urgency, Impact)` |
| Default fallback priority | The Phase-2 `default: true` entry's `valueName` already equals the requested value |
| Salesforce Go step completion (route 10) | No functional Phase-4 write was dispatched this run — i.e. the request was view-only, or every targeted concern was itself an idempotent no-op. The PUT is also idempotent server-side, so re-asserting `isComplete: true` after a real write is harmless |

When a functional concern (the first six rows) is idempotent, report `ALREADY-<state>` and skip Phase 4 entirely. Route 10 is a Phase-5 action, not a Phase-4 concern — it has no `ALREADY-<state>` report.

---

## Picklist extraction

From the Phase-1 Incident describe response, iterate `fields[]`:

- Look up each field by exact `name` (`Impact`, `Urgency`, `Priority`).
- Keep only `picklistValues[]` entries with `active == true`.
- Use `value` (API name), not `label` — the server stores API values on `ServiceOpPriorityConfig`.

If the describe response is very large, dispatch a subagent (haiku tier) to extract just the three picklists.

Every `Impact`, `Urgency`, `Priority` in an add or change payload — including the default value in the `StandardValueSet` deploy — must be in the fetched active set. Never hardcode `High/Medium/Low` or `Critical/High/Moderate/Low`; customers rename, add, or remove values.

For an uncustomized org the defaults are `High/Medium/Low` on `Impact` and `Urgency`, and `Critical/High/Moderate/Low` on `Priority` — treat as examples, not guarantees.

---

## Gotchas

| Issue | Detail |
|-------|--------|
| Tooling REST accepts garbage picklist values | The wire-level POST/PATCH does NOT validate `Urgency` / `Impact` / `Priority` against the picklist. Runtime matrix evaluation ignores garbage rows. Always validate client-side before dispatch. |
| Duplicate `(ReferenceObject, Urgency, Impact)` rows | Accepted silently at the wire level — the server does NOT enforce uniqueness. Both rows persist and the runtime picks one non-deterministically. Deduplicate against the Phase-2 snapshot before POST; this check is the only guard. |
| `ReferenceObject` accepts any string | The `ServiceOpPriorityConfig` SObject is shared with `Problem` and `ChangeRequest` matrices; the server accepts any value in `ReferenceObject`. Scope to `Incident` is skill-enforced only — refuse other values client-side. |
| `sf api request rest ... --method DELETE` on Tooling | Fails with `SfError: No 'mode' found in 'body' entry` (sf CLI 2.143). Use `sf data delete record --use-tooling-api` instead. |
| Direct PATCH on `StandardValueSet/<Id>` via Tooling REST | Returns `FIELD_INTEGRITY_EXCEPTION: Unable to load specified entity`. Metadata deploy is the canonical path for picklist defaults. |
| Existing Incidents' Priority | Not re-derived on matrix change. New writes use the new matrix; the stamped Priority on existing Incident records stays put. |
| Salesforce Go "Define Priority Matrix" step stays "not done" after configuring the matrix | The step is user-override — its checkmark is a `StepProgress` record, not derived from org state, so functional writes alone never flip it. Send route 10's completion PUT after the write (see step 8 in the SKILL Workflow). Omitting `isComplete` in the body → HTTP 500, not 400. |
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall