工作流程

client.workflows 管理 Imbrace 流程引擎：建立和觸發自動化流程、檢視執行歷史、使用資料夾組織、管理應用程式連線和 MCP 伺服器，以及存取工作流程表格。

結構定義

Flow

欄位	類型	說明
`id`	string	唯一流程 ID
`created`	string	ISO 8601 建立時間戳
`updated`	string	ISO 8601 更新時間戳
`projectId`	string	所屬專案
`externalId`	string	選用外部識別碼
`status`	`"ENABLED"` \| `"DISABLED"`	流程是否啟用
`operationStatus`	string	目前操作狀態
`version`	FlowVersion	啟用中的版本物件

FlowVersion

欄位	類型	說明
`id`	string	唯一版本 ID
`created`	string	ISO 8601 建立時間戳
`updated`	string	ISO 8601 更新時間戳
`flowId`	string	此版本所屬的流程
`displayName`	string	人類可讀的流程名稱
`trigger`	object	觸發器設定
`steps`	object?	選用的步驟設定
`valid`	boolean?	版本是否有效

FlowRun

欄位	類型	說明
`id`	string	唯一執行 ID
`created`	string	ISO 8601 建立時間戳
`updated`	string	ISO 8601 更新時間戳
`projectId`	string	專案 ID
`flowId`	string	已執行的流程
`flowVersionId`	string	執行的特定版本
`status`	`"RUNNING"` \| `"SUCCEEDED"` \| `"FAILED"` \| `"TIMEOUT"` \| `"PAUSED"` \| `"STOPPED"`	執行結果
`environment`	`"PRODUCTION"` \| `"TESTING"`	執行環境
`startTime`	string?	執行開始時間
`finishTime`	string?	執行結束時間
`failParentOnFailure`	boolean	失敗是否傳播至父流程
`tags`	string[]?	附加到此執行的標籤

AppConnection

欄位	類型	說明
`id`	string	唯一連線 ID
`created`	string	ISO 8601 建立時間戳
`updated`	string	ISO 8601 更新時間戳
`externalId`	string	外部識別碼
`displayName`	string	人類可讀名稱
`pieceName`	string	此連線所屬的 piece（整合）
`projectId`	string	專案 ID
`type`	`"SECRET_TEXT"` \| `"OAUTH2"` \| `"CLOUD_OAUTH2"` \| `"PLATFORM_OAUTH2"` \| `"BASIC_AUTH"` \| `"CUSTOM_AUTH"`	連線驗證類型

McpServer

欄位	類型	說明
`id`	string	唯一 MCP 伺服器 ID
`created`	string	ISO 8601 建立時間戳
`updated`	string	ISO 8601 更新時間戳
`projectId`	string	專案 ID
`name`	string?	伺服器名稱

方法

流程

方法	TypeScript	Python	說明
列出流程	`listFlows`	`list_flows`	分頁的流程列表
取得流程	`getFlow`	`get_flow`	依 ID 取得單一流程
建立流程	`createFlow`	`create_flow`	建立新流程
刪除流程	`deleteFlow`	`delete_flow`	刪除流程
套用流程操作	`applyFlowOperation`	`apply_flow_operation`	對流程套用操作（例如發佈、啟用）
觸發流程	`triggerFlow`	`trigger_flow`	非同步觸發流程
同步觸發流程	`triggerFlowSync`	`trigger_flow_sync`	觸發流程並等待結果

流程執行紀錄

方法	TypeScript	Python	說明
列出執行紀錄	`listRuns`	`list_runs`	列出執行歷史
取得執行紀錄	`getRun`	`get_run`	依 ID 取得單一執行

資料夾

方法	TypeScript	Python	說明
列出資料夾	`listFolders`	`list_folders`	列出流程資料夾
取得資料夾	`getFolder`	`get_folder`	依 ID 取得資料夾
建立資料夾	`createFolder`	`create_folder`	建立資料夾
更新資料夾	`updateFolder`	`update_folder`	重新命名資料夾
刪除資料夾	`deleteFolder`	`delete_folder`	刪除資料夾

應用程式連線

方法	TypeScript	Python	說明
列出連線	`listConnections`	`list_connections`	列出應用程式連線
取得連線	`getConnection`	`get_connection`	依 ID 取得連線
新增或更新連線	`upsertConnection`	`upsert_connection`	建立或更新連線
刪除連線	`deleteConnection`	`delete_connection`	移除連線

MCP 伺服器

方法	TypeScript	Python	說明
列出 MCP 伺服器	`listMcpServers`	`list_mcp_servers`	列出 MCP 伺服器
取得 MCP 伺服器	`getMcpServer`	`get_mcp_server`	依 ID 取得伺服器
建立 MCP 伺服器	`createMcpServer`	`create_mcp_server`	註冊新的 MCP 伺服器
刪除 MCP 伺服器	`deleteMcpServer`	`delete_mcp_server`	移除伺服器
輪替權杖	`rotateMcpToken`	`rotate_mcp_token`	輪替伺服器的驗證權杖

const page = await client.workflows.listFlows({
  limit: 10,
  status: "ENABLED",
  folderId: "folder_id",
});
for (const flow of page.data) {
  console.log(flow.id, flow.version?.displayName);
}

page = client.workflows.list_flows(limit=10, status="ENABLED", folder_id="folder_id")
for flow in page.get("data", []):
    print(flow["id"])

createFlow / create_flow

TypeScript
Python

const flow = await client.workflows.createFlow({
  displayName: "New Lead Notification",
  projectId: "project_id",
});
console.log(flow.id);

flow = client.workflows.create_flow(
    display_name="New Lead Notification",
    project_id="project_id",
)
print(flow["id"])

triggerFlow / trigger_flow

非同步觸發流程，可附帶選用的酬載。

TypeScript
Python

await client.workflows.triggerFlow("flow_id", {
  contact_id: "contact_123",
  event: "lead_created",
});

client.workflows.trigger_flow("flow_id", {
    "contact_id": "contact_123",
    "event": "lead_created",
})

listRuns / list_runs

TypeScript
Python

const page = await client.workflows.listRuns({
  flowId: "flow_id",
  status: "FAILED",
  limit: 20,
});

page = client.workflows.list_runs(
    flow_id="flow_id",
    status="FAILED",
    limit=20,
)

upsertConnection / upsert_connection

建立或更新應用程式連線（例如第三方服務的 API 金鑰）。

TypeScript
Python

const conn = await client.workflows.upsertConnection({
  displayName: "Slack Workspace",
  pieceName: "slack",
  projectId: "project_id",
  type: "SECRET_TEXT",
  value: { api_key: "xoxb-..." },
});

conn = client.workflows.upsert_connection({
    "displayName": "Slack Workspace",
    "pieceName": "slack",
    "projectId": "project_id",
    "type": "SECRET_TEXT",
    "value": {"api_key": "xoxb-..."},
})

createMcpServer / create_mcp_server

TypeScript
Python

const server = await client.workflows.createMcpServer({
  name: "My MCP Server",
  projectId: "project_id",
});

server = client.workflows.create_mcp_server({
    "name": "My MCP Server",
    "projectId": "project_id",
})