API 参考 / work-items

工作项的完整状态机与当前可走的边

GET /api/v1/work-items/{workItemId}/workflow · getWorkItemWorkflow

一次拿到该工作项自己钉定的工作流版本的完整状态机（states / slots / transitions， 含每条边的 guards 原始 config、actions 与 route）以及当前状态下逐边的可用性判定。 在此之前，外部调用方要拼出同样的视图得发三个请求：GET /projects/{projectId}/workflow-bindings 取绑定 → GET /projects/{projectId}/workflows/{templateId}/versions/{versionId} 取图 → GET .../transitions 取当前可走的边；而且拿到的是项目当前绑定的版本，对象钉在旧版本时 展示与求值会漂移。本端点恒按对象自己钉的 workflowVersionId 返回，不会漂。 用途：外部流程在下发纪律前先校验其可执行性——「这个项目的工作项能不能从 A 直接走到 B」看 transitions 的拓扑，「我现在能不能走」看 availableTransitions[].allowed。 状态机的形状由项目管理员在 /settings/workflows 配置：内置需求工作流从 backlog 只能到 in_review / rejected，要加别的出边请在那里改，不是 API 的限制。 templateId 供拼配置面链接与调既有的版本详情端点；模板名从 GET /projects/{projectId}/workflows 取。 权限与 GET .../transitions 同档（响应内含逐边 availability）。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

参数

workItemId（必填）
string

响应字段 · 200

templateId（必填）
string
versionId（必填）
string
versionNo（必填）
integer
currentStateKey（必填）
string
states（必填）
WorkflowState[]
states[].key（必填）
string
states[].name（必填）
string
states[].semantic（必填）
string
states[].color
string
states[].position
integer
states[].isInitial（必填）
boolean
states[].isTerminal（必填）
boolean
states[].layout
object
slots（必填）
WorkflowSlot[]
slots[].key（必填）
string
slots[].name（必填）
string
slots[].origin（必填）
string
slots[].cardinality（必填）
enum；取值：single / multi
slots[].multiResolution
string
slots[].isOwnerSlot（必填）
boolean
slots[].sortOrder
integer
transitions（必填）
WorkflowTransition[]
transitions[].id
string
transitions[].name
string
transitions[].fromKey
string
transitions[].toKey（必填）
string
transitions[].global（必填）
boolean
transitions[].requireReason
boolean
transitions[].sortOrder
integer
transitions[].guards
WorkflowGuard[]
transitions[].guards[].phase（必填）
string
transitions[].guards[].type（必填）
string
transitions[].guards[].config
object
transitions[].guards[].errorMessage
string
transitions[].guards[].sortOrder（必填）
integer
transitions[].guards[].enabled（必填）
boolean
transitions[].actions
WorkflowAction[]
transitions[].actions[].kind（必填）
enum；取值：set_field
transitions[].actions[].fieldKey
string —— set_field 目标字段键（如 progress / resolution）。
transitions[].actions[].value
string —— 要写入目标字段的值（字符串承载，set_field 应用时按字段类型解释）。
transitions[].route
WorkflowRoute
transitions[].route.targetSlotKey（必填）
string
transitions[].route.emptyFallback
string
transitions[].route.notifyPolicy
string
availableTransitions（必填）
WorkItemTransition[]
availableTransitions[].toStateKey（必填）
string
availableTransitions[].name（必填）
string
availableTransitions[].allowed（必填）
boolean
availableTransitions[].blockedReason
string
availableTransitions[].guardCode
enum；取值：permission / missing_field / separation_of_duties / slot_empty / not_slot_member / not_visited / unknown
availableTransitions[].requireReason
boolean
availableTransitions[].href（必填）
string
availableTransitions[].method（必填）
string

错误

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/work-items/{workItemId}/workflow" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "templateId": "018f3c2e-0000-7000-8000-000000000000",
  "versionId": "018f3c2e-0000-7000-8000-000000000000",
  "versionNo": 1,
  "currentStateKey": "示例文本",
  "states": [
    {
      "key": "示例文本",
      "name": "示例标题",
      "semantic": "示例文本",
      "isInitial": true,
      "isTerminal": true
    }
  ],
  "slots": [
    {
      "key": "示例文本",
      "name": "示例标题",
      "origin": "示例文本",
      "cardinality": "single",
      "isOwnerSlot": true
    }
  ],
  "transitions": [
    {
      "toKey": "示例文本",
      "global": true,
      "id": "018f3c2e-0000-7000-8000-000000000000"
    }
  ],
  "availableTransitions": [
    {
      "toStateKey": "示例文本",
      "name": "示例标题",
      "allowed": true,
      "href": "示例文本",
      "method": "示例文本"
    }
  ]
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引

Workflow 正在加载…