Back to Details

service-itsm-incident-mgmt-configure

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Configuring ITSM Incident Management (master toggle)

配置ITSM事件管理（主开关）

Read and toggle the master Incident Management setting on a Salesforce ITSM org. This is the org-level switch that turns Incident Management on or off. Enabling it also brings up its sub-features on the server side, so a full enablement is a single operation on the master.
Writes are idempotent (skipped when the current status already matches the requested state), the skill always reads before it writes, and an explicit confirm-to-write checkpoint is required before any mutation.
读取并切换Salesforce ITSM组织上的事件管理主设置。这是用于开启或关闭事件管理的组织级开关。启用该开关时，服务器端会同时启用其子功能，因此只需对主开关执行一次操作即可完成完整启用。
写入操作具备幂等性（当当前状态与请求状态一致时会跳过操作），该技能始终先读取再写入，且在进行任何变更前需要经过明确的确认写入检查点。

What this skill controls

此技能管控的范围

Preference (Setup UI label)In scope
Incident Management enablement (master)Yes — read and toggle
Default Field Validations for Incidents, Auto Closure of Child Incidents, Email-to-Incident sub-toggles, Incident Priority Matrix, Problem/Change/Case Management, ITSM External Client App setupNo
For the exact URLs, wire shapes, and worked examples for the master read and write, see 
references/mcp-invocation.md
.
偏好设置（设置UI标签）是否在范围内
事件管理启用（主开关）是 — 可读取和切换
事件默认字段验证、子事件自动关闭、邮件转事件子开关、事件优先级矩阵、问题/变更/案例管理、ITSM外部客户端应用设置否
有关主开关读取和写入的准确URL、请求格式及示例，请查看
references/mcp-invocation.md
。

Scope

范围界定

  • In scope: read and toggle the master Incident Management preference.
  • Out of scope: Default Field Validations for Incidents (
    IncidentValidationsEnabled
    ); Incident Priority Matrix configuration; Auto Closure of Child Incidents and Email-to-Incident sub-toggles; Problem Management; Change Management; Case Management; ITSM External Client App setup; other ITSM prefs (
    IncidentTriageAgentEnabled
    , 
    IncAssignWithAgentEnabled
    , 
    AssignedGroupValidationEnabled
    ); broadcast-channel prefs; creation or configuration of Incident, Problem, or ChangeRequest records.
  • 包含范围：读取和切换事件管理主偏好设置。
  • 排除范围：事件默认字段验证（
    IncidentValidationsEnabled
    ）；事件优先级矩阵配置；子事件自动关闭和邮件转事件子开关；问题管理；变更管理；案例管理；ITSM外部客户端应用设置；其他ITSM偏好设置（
    IncidentTriageAgentEnabled
    、
    IncAssignWithAgentEnabled
    、
    AssignedGroupValidationEnabled
    ）；广播渠道偏好设置；事件、问题或变更请求记录的创建或配置。

Preconditions

前置条件

Before the skill can call anything on 
headless-360
, the target org and MCP client must be configured. If any of these are unmet, the tools will surface as 
401
, 
403
, or 
404
on the first call; do not fabricate state — surface the raw error and stop.
  1. Server activated on the org: Setup → MCP Servers → 
    headless-360
    → Activate. Activation can take up to ~2 minutes.
  2. External Client App wired: an ECA in the org with OAuth scopes 
    mcp_api
    and 
    refresh_token
    , JWT-based access tokens enabled, PKCE required. ECA propagation can take up to 30 minutes.
  3. API v67.0+: required for the read and write routes this skill uses.
  4. MCP client registration: the client (adk-eval / Claude Code) has an 
    additionalServers.headless-360
    entry pointing to the correct env URL (see 
    references/mcp-invocation.md
    ).
If any precondition fails, the tools return one of:
  • 401 Unauthorized
    → ECA not propagated, wrong scopes, or expired token.
  • 403 Forbidden
    → user lacks perm, or org missing 
    IncidentMgmt.orgHasITSMOrgPermission
    .
  • 404 Not Found
    → server not activated on the org.
Report the raw response verbatim rather than guessing which precondition failed.
在技能调用
headless-360
的任何功能之前，必须配置好目标组织和MCP客户端。如果任何条件未满足，工具首次调用时会返回
401
、
403
或
404
；请勿编造状态——直接返回原始错误并终止操作。
  1. 组织上的服务器已激活：设置 → MCP服务器 → 
    headless-360
    → 激活。激活过程可能需要约2分钟。
  2. 外部客户端应用已配置：组织中存在一个ECA，其OAuth范围包含
    mcp_api
    和
    refresh_token
    ，已启用基于JWT的访问令牌，且要求PKCE。ECA配置生效可能需要长达30分钟。
  3. API v67.0+：此技能使用的读取和写入路由需要该版本以上的API。
  4. MCP客户端已注册：客户端（adk-eval / Claude Code）的
    additionalServers.headless-360
    条目指向正确的环境URL（请查看
    references/mcp-invocation.md
    ）。
如果任何前置条件未满足，工具会返回以下错误之一：
  • 401 Unauthorized
    → ECA未生效、范围错误或令牌过期。
  • 403 Forbidden
    → 用户无权限，或组织缺少
    IncidentMgmt.orgHasITSMOrgPermission
    权限。
  • 404 Not Found
    → 组织上的服务器未激活。
请直接返回原始响应内容，不要猜测是哪个前置条件未满足。

Architecture — How configuration works

架构——配置工作流程

StepWhat happensTool
PreflightConfirm the target routes are reachable
describe
, 
dispatch_readonly
Read schemaFetch the request/response contract for the read and the write
describe
Read current stateFetch the current status of the master preference
dispatch_readonly
Decide operationView / enable / disable — inferred from the prompt—
Confirm-to-writePresent 
(status: current → requested)
and require explicit "yes"		—
Apply changeEnable or disable the master via the write route
dispatch
VerifyRe-read and compare against the requested state
dispatch_readonly
Idempotency: after the Phase-3 read, if the current state already matches the requested state, skip Phase 5 and treat the operation as a no-op. 
references/mcp-invocation.md
documents the exact status field and match rule.
Read-only tool selection: use 
dispatch_readonly
for the read. Use 
dispatch
for the write. The server refuses mutating operations through 
dispatch_readonly
.
Wire shape: 
dispatch
and 
dispatch_readonly
both take 
{"url": "/services/data/...", "method": "GET|POST|PATCH|...", "body"?: {...}, "query_params"?: {...}}
. See 
references/mcp-invocation.md
for the exact request/response shapes; call 
describe
at runtime to confirm.
步骤操作内容工具
预检确认目标路由可访问
describe
、
dispatch_readonly
读取 schema获取读取和写入操作的请求/响应契约
describe
读取当前状态获取主偏好设置的当前状态
dispatch_readonly
确定操作查看/启用/禁用——根据用户提示推断—
确认写入展示
(状态: 当前 → 请求)
并要求明确回复“yes”		—
应用变更通过写入路由启用或禁用主开关
dispatch
验证重新读取状态并与请求状态对比
dispatch_readonly
幂等性：在步骤3读取后，如果当前状态已与请求状态一致，则跳过步骤5，将操作视为无操作。
references/mcp-invocation.md
文档中记录了准确的状态字段和匹配规则。
只读工具选择：读取操作使用
dispatch_readonly
，写入操作使用
dispatch
。服务器拒绝通过
dispatch_readonly
执行变更操作。
请求格式：
dispatch
和
dispatch_readonly
均接受
{"url": "/services/data/...", "method": "GET|POST|PATCH|...", "body"?: {...}, "query_params"?: {...}}
格式。请查看
references/mcp-invocation.md
获取准确的请求/响应格式；运行时可调用
describe
进行确认。

Clarifying Questions

澄清问题

Ask only what is not already in conversation context:
FieldDescriptionDefault
Requested directionExplicit 
enable
/ 
disable
(or 
on
/ 
off
)		REQUIRED — no defaults; ask if the user only said "toggle" without a direction
Confirm writeExplicit "yes" before any 
dispatch
mutation		REQUIRED — see Phase 4
If the user says "toggle" without specifying a direction, ask for the direction before Phase 4. Do not infer it from the current state.
仅询问对话上下文未涵盖的内容：
字段描述默认值
请求方向明确的
enable
/
disable
（或
on
/
off
）		必填——无默认值；如果用户仅说“toggle”未指定方向，请询问
确认写入在执行任何
dispatch
变更前需要明确回复“yes”		必填——请查看步骤4
如果用户仅说“toggle”未指定方向，请在步骤4前询问方向。请勿根据当前状态推断方向。

Workflow

工作流程

All steps run against the 
headless-360
MCP server; the tool namespace is 
mcp__headless-360__<tool-name>
.
所有步骤均针对
headless-360
MCP服务器运行；工具命名空间为
mcp__headless-360__<tool-name>
。

Phase 0 — Reuse what the session already knows

步骤0——复用会话已知信息

Each preflight read below carries a skip-if-already-known clause. Before calling any read endpoint, check whether an earlier turn in this session already produced the same fact from a successful tool response tied to the current org (a prior invocation of this skill, a parent orchestrator's live read, or an earlier 
dispatch_readonly
this run). An explicit user statement is NOT a substitute for a live read of the master preference — user assertions can be stale or mistaken, and this skill relies on the read being the source of truth for the confirmation payload and the Phase-6 idempotency verify. When the only source is a user statement, re-read.
  • describe
    of the master read/write routes     — if the request/response schemas were already fetched against the current org this session, skip Phase 1 and Phase 2 and reuse the cached schema. 
    describe
    output is stable within a session.
  • Current master preference state — if the master 
    IncidentMgmtEnabled
    value for the current org was already read this session via a successful 
    dispatch_readonly
    response     (Phase 3 result from an earlier run of this skill, or a parent orchestrator that already asked us to check), skip Phase 3 and reuse the recorded "before" value. A user's verbal claim that the switch is on or off is not cache-eligible.
When in doubt, re-check. Skip only when the earlier fact is unambiguously in context AND you have not switched orgs — the 
headless-360
MCP session binds to one org via the JWT, so an org change is only possible if the session was re-authed mid-conversation. If the user hints at a different org, or you cannot tell which org the earlier fact came from, re-run the read. Note: any 
dispatch
write elsewhere in the session that could have flipped the master (this skill's Phase 5, or an admin change via another tool) also invalidates the cache — re-read. A wrong skip on a live org write is worse than a duplicated read.
以下每个预检读取操作均带有已知则跳过规则。调用任何读取端点前，请检查本次会话中是否已有针对当前组织的成功工具响应生成了相同信息（此技能的先前调用、父编排器的实时读取或本次运行中较早的
dispatch_readonly
操作）。用户的明确陈述不能替代对主偏好设置的实时读取——用户的断言可能过时或错误，此技能依赖读取结果作为确认负载和步骤6幂等性验证的事实来源。当唯一信息来源是用户陈述时，请重新读取。
  • 主开关读取/写入路由的
    describe
    ——如果本次会话中已针对当前组织获取过请求/响应schema，则跳过步骤1和步骤2，复用缓存的schema。
    describe
    输出在会话内是稳定的。
  • 当前主偏好设置状态——如果本次会话中已通过成功的
    dispatch_readonly
    响应读取过当前组织的主开关
    IncidentMgmtEnabled
    值（此技能先前运行的步骤3结果，或已要求我们检查的父编排器），则跳过步骤3，复用记录的“变更前”值。用户口头声称开关开启或关闭不具备缓存资格。
如有疑问，请重新检查。仅当先前信息明确在上下文中且未切换组织时才跳过——
headless-360
MCP会话通过JWT绑定到一个组织，因此只有在会话中途重新认证时才可能切换组织。如果用户暗示切换了组织，或无法确定先前信息来自哪个组织，请重新运行读取操作。注意：会话中任何可能翻转主开关的
dispatch
写入操作（此技能的步骤5，或通过其他工具进行的管理员变更）都会使缓存失效——请重新读取。错误跳过实时组织写入比重复读取更严重。

Phase 1 — Preflight (
discover
/ 
describe
)

步骤1——预检（
discover
/
describe
）

  1. (Skip if the operation schemas were already verified this session — see Phase 0.) Call 
    describe
    on the read/write routes (or 
    discover
    with a query like 
    "ITSM incident management setup discovery"
    if the operation IDs are unknown). Confirm the operations exist and their argument schemas match 
    references/mcp-invocation.md
    .
  2. If any tool call returns 
    401
    / 
    403
    / 
    404
    , halt and surface the raw error — the org or client is not configured correctly (see Preconditions).
  1. （如果本次会话中已验证过操作schema则跳过——请查看步骤0。） 对读取/写入路由调用
    describe
    （如果操作ID未知，可使用类似
    "ITSM incident management setup discovery"
    的查询调用
    discover
    ）。确认操作存在且其参数schema与
    references/mcp-invocation.md
    匹配。
  2. 如果任何工具调用返回
    401
    /
    403
    /
    404
    ，则终止操作并返回原始错误——组织或客户端配置不正确（请查看前置条件）。

Phase 2 — Load Schemas (
describe
)

步骤2——加载Schema（
describe
）

  1. (Skip if the schema for each operation is already cached this session — see Phase 0.) For each operation the invocation will use, call 
    describe
    and cache the returned request/response schema. Do not hard-code the argument shape from the reference doc — read it from 
    describe
    ; the docs are a working expectation, the runtime contract is whatever 
    describe
    returns.
  1. （如果本次会话中已缓存每个操作的schema则跳过——请查看步骤0。） 对调用将使用的每个操作，调用
    describe
    并缓存返回的请求/响应schema。请勿从参考文档硬编码参数格式——请从
    describe
    读取；文档是预期格式，运行时契约以
    describe
    返回内容为准。

Phase 3 — Read Current State (
dispatch_readonly
)

步骤3——读取当前状态（
dispatch_readonly
）

  1. (Skip if the current master state for this org was already read this session AND no write has flipped it since — see Phase 0.) Read the current state of the master preference using the read route documented in 
    references/mcp-invocation.md
    . Record the value as the "before" state for the Phase-4 confirmation and the Phase-6 verify.
    For a view-only request, stop after Phase 3 and go to Phase 7 to report.
  1. （如果本次会话中已读取当前组织的主开关状态且之后未进行写入操作则跳过——请查看步骤0。） 使用
    references/mcp-invocation.md
    中记录的读取路由读取主偏好设置的当前状态。记录该值作为步骤4确认和步骤6验证的“变更前”状态。
    如果是仅查看请求，则在步骤3后停止，进入步骤7报告结果。

Phase 4 — Decide Operation + Confirm-to-Write (REQUIRED for any write)

步骤4——确定操作+确认写入（任何写入操作均必填）

  1. Decide the operation from the user's prompt (view / enable / disable). If the user said "toggle" without a direction, ask for the direction first.
  2. Present the target payload via 
    AskUserQuestion
    as 
    (Master Incident Management: <current> → <requested>)
    . Require an explicit "yes" before proceeding. Proceed to Phase 5 ONLY on explicit "yes". On "no", stop and report the current state without writing.
  1. 根据用户提示确定操作（查看/启用/禁用）。如果用户仅说“toggle”未指定方向，请先询问方向。
  2. 通过
    AskUserQuestion
    展示目标负载：
    (事件管理主开关: <当前状态> → <请求状态>)
    。要求用户明确回复“yes”后再继续。仅在明确回复“yes”时才进入步骤5。如果回复“no”，则终止操作并报告当前状态，不执行写入。

Phase 5 — Apply the Change (skip for view-only)

步骤5——应用变更（仅查看请求跳过）

  1. Apply the idempotency rule from 
    references/mcp-invocation.md
    : if the current state already matches the requested state, skip Phase 5 and mark the operation as an idempotent no-op.
  2. Otherwise, dispatch the write via 
    dispatch
    using the enable or disable route documented in 
    references/mcp-invocation.md
    . Enabling the master brings up the Incident Management sub-features on the server side — no separate calls are needed to turn them on. Disabling the master leaves those sub-features at their last-set values.
  3. On error (
    4xx
    , 
    5xx
    ), record the raw response verbatim and stop.
  1. 应用
    references/mcp-invocation.md
    中的幂等规则：如果当前状态已与请求状态一致，则跳过步骤5，将操作标记为幂等无操作。
  2. 否则，使用
    references/mcp-invocation.md
    中记录的启用或禁用路由，通过
    dispatch
    执行写入操作。启用主开关时，服务器端会同时启用事件管理子功能——无需单独调用开启这些子功能。禁用主开关时，这些子功能会保留其最后设置的值。
  3. 如果出现错误（
    4xx
    、
    5xx
    ），记录原始响应内容并终止操作。

Phase 6 — Verify (
dispatch_readonly
)

步骤6——验证（
dispatch_readonly
）

  1. Re-issue the Phase-3 read and compare against the requested state per the rule in 
    references/mcp-invocation.md
    . If they differ, treat it as a failed write and report the raw server response verbatim.
  1. 重新执行步骤3的读取操作，并根据
    references/mcp-invocation.md
    中的规则与请求状态对比。如果不一致，则视为写入失败，直接返回原始服务器响应内容。

Phase 7 — Report

步骤7——报告

  1. Present a before/after summary:
    • View: 
      Master Incident Management: <current-status>
      .
    • Toggle: 
      Master Incident Management: <before> → <after>
      with verdict 
      SUCCEEDED
      / 
      ALREADY-<state>
      / 
      FAILED
      .
    • On Phase-6 mismatch: 
      write FAILED — server state differs from request. Server response: <verbatim>
      .
  1. 展示变更前后的摘要：
    • 查看：
      事件管理主开关: <当前状态>
      。
    • 切换：
      事件管理主开关: <变更前> → <变更后>
      ，并附带结果
      SUCCEEDED
      /
      ALREADY-<状态>
      /
      FAILED
      。
    • 如果步骤6出现不一致：
      写入失败——服务器状态与请求不符。服务器响应: <原始内容>
      。

Rules / Constraints

规则/约束

ConstraintRationale
All operations run through the four hosted 
headless-360
tools		The hosted MCP is the required transport
Read the argument schema for each operation via 
describe
before calling 
dispatch
/ 
dispatch_readonly
The runtime contract is what 
describe
returns; do not hard-code
Use 
dispatch_readonly
for the read; use 
dispatch
for the write		The server refuses mutating operations through 
dispatch_readonly
Always set/expect API v67.0 minimumThe read and write routes require v67+
Read live state before writingThe Phase-3 fetch is the source of truth for the confirmation prompt, the idempotency check, and the Phase-6 verify
REQUIRED confirm-to-write checkpoint before any 
dispatch
mutation		Toggling this pref mutates org state; user must approve the exact plan
Idempotent — skip 
dispatch
when the current state already matches the requested state		Avoids no-op writes; see 
references/mcp-invocation.md
for the exact match rule
Report exact error text from the MCP tool responseThe server surfaces the underlying error message verbatim
On 
401
/ 
403
/ 
404
in Phase 1, halt and surface the raw error		The failing precondition is diagnosable only from the raw response
Do not put an orgId or Core URL in the 
dispatch
arguments		The server derives the target org from the JWT issuer on the request
约束理由
所有操作均通过四个托管的
headless-360
工具运行		托管MCP是必需的传输方式
在调用
dispatch
/
dispatch_readonly
前，通过
describe
读取每个操作的参数schema		运行时契约以
describe
返回内容为准；请勿硬编码
读取操作使用
dispatch_readonly
；写入操作使用
dispatch
服务器拒绝通过
dispatch_readonly
执行变更操作
始终设置/要求最低API v67.0读取和写入路由需要v67+版本
写入前读取实时状态步骤3的读取结果是确认提示、幂等性检查和步骤6验证的事实来源
必填的确认写入检查点——在执行任何
dispatch
变更前		切换此偏好设置会修改组织状态；用户必须批准确切的操作计划
幂等性——当当前状态已与请求状态一致时跳过
dispatch
避免无意义的写入操作；请查看
references/mcp-invocation.md
获取准确的匹配规则
直接返回MCP工具响应中的错误文本服务器会直接返回底层错误信息
如果步骤1中出现
401
/
403
/
404
，则终止操作并返回原始错误		只有原始响应才能诊断未满足的前置条件
请勿在
dispatch
参数中放入orgId或核心URL		服务器会从请求中的JWT颁发者推导目标组织

Verification Checklist

验证清单

Before reporting completion of any mutation, confirm each of the following. If any item is unchecked, do not report success — surface what is missing.
  • Phase 1 preflight (
    describe
    / 
    discover
    ) returned the operation without a 
    401
    / 
    403
    / 
    404
    ; if any was returned, the raw error was surfaced and the run halted.
  • Phase 3 read against the master preference returned a status and that value was recorded as the "before" state.
  • Phase 4 confirm-to-write presented 
    (Master Incident Management: <current> → <requested>)
    via 
    AskUserQuestion
    and the user replied with an explicit "yes" — no write dispatched on any other response (silence, "maybe", "looks good", implicit approval).
  • Idempotency: if the current state already matched the requested state, Phase 5 was skipped and the run was reported as an idempotent no-op — no 
    dispatch
    write was issued.
  • Phase 5 write used 
    dispatch
    (not 
    dispatch_readonly
    ) with the wire shape from 
    references/mcp-invocation.md
    ; on any 
    4xx
    / 
    5xx
    , the raw response was surfaced and the run halted.
  • Phase 6 verify re-issued the Phase-3 read and the post-write state matched the user-approved target; any diff was reported as 
    write FAILED — server state differs from request
    .
  • The final report gave a before/after for the master preference with verdict 
    SUCCEEDED
    / 
    ALREADY-<state>
    / 
    FAILED
    .
在报告任何变更完成前，请确认以下各项。如果有任何一项未勾选，则不要报告成功——请说明缺失的内容。
  • 步骤1预检（
    describe
    /
    discover
    ）返回操作且未出现
    401
    /
    403
    /
    404
    ；如果出现上述错误，已返回原始错误并终止运行。
  • 步骤3读取主偏好设置返回状态，且该值已记录为“变更前”状态。
  • 步骤4确认写入通过
    AskUserQuestion
    展示了
    (事件管理主开关: <当前状态> → <请求状态>)
    ，且用户明确回复“yes”——未在其他回复（沉默、“maybe”、“看起来不错”、隐含批准）时执行写入。
  • 幂等性：如果当前状态已与请求状态一致，则跳过步骤5，将运行报告为幂等无操作——未执行
    dispatch
    写入。
  • 步骤5写入使用
    dispatch
    （而非
    dispatch_readonly
    ），且请求格式符合
    references/mcp-invocation.md
    ；如果出现任何
    4xx
    /
    5xx
    错误，已返回原始响应并终止运行。
  • 步骤6验证重新执行了步骤3的读取操作，且写入后的状态与用户批准的目标一致；任何差异均报告为
    写入失败——服务器状态与请求不符
    。
  • 最终报告提供了主偏好设置的变更前后状态，并附带结果
    SUCCEEDED
    /
    ALREADY-<状态>
    /
    FAILED
    。

Reference File Index

参考文件索引

FileWhen to read
references/mcp-invocation.md
Exact tool call shapes for the master read and write, MCP-client registration recipe for 
headless-360
in 
mcp-config.json
, External Client App setup checklist (
mcp_api
scope, PKCE, JWT), Headless-360 error taxonomy, and a worked enable/disable example
文件阅读时机
references/mcp-invocation.md
主开关读取和写入的准确工具调用格式、
mcp-config.json
中
headless-360
的MCP客户端注册指南、外部客户端应用设置清单（
mcp_api
范围、PKCE、JWT）、Headless-360错误分类，以及启用/禁用的示例