UIP Maestro 案例

使用“uip Maestro Case”创建、打包、调试、验证和创作案例管理项目，这是在 BPMN 和 Flow 之后的第三个 Maestro 编排界面。

uip maestro case用于创建、打包、调试和创作案例管理项目，这是除了BPMN和Flow之外的第三个 Maestro 编排界面。案例项目将长时间运行的人工驱动工作单元建模为案例计划：一个 JSON 文档 ( caseplan.json )，描述阶段、任务、SLA、触发器以及在不同阶段之间移动案例的进入/退出条件 —比线性流程更接近于有生命周期的结构化工作流。

该工具作为单独的 @uipath/case-tool 包提供，由 @uipath/maestro-tool 分支下的 case 动态加载 — 此处的每个命令都作为 uip maestro case <verb> 调用，从不作为独立的 uip case 调用。

该资源跨越九个页面

• 本页— 概念和项目生命周期命令： init 、 pack 、 debug 、 validate 、 spec 。
• registry — 浏览/搜索案例连接任务到的自动化资源目录，以及如何将任务输入绑定到变量。
• cases和stages — 读取案例计划的顶层元数据和阶段列表。
• tasks — 读取、丰富并描述阶段中的任务定义。
• task-entry-conditions — 阅读控制任务何时可运行的规则。
• sla — 读取 SLA/升级规则。
• triggers 、 sticky-notes 、 edges — 读取案例触发器、画布注释和阶段到阶段转换。
• case-exit-conditions 、 stage-entry-conditions 、 stage-exit-conditions — 阅读案例级别和阶段级别条件规则。
• process 、 processes 、 job 、 instances 、 incidents — 在 Orchestrator 上部署并运行案例实例。

概念

• 创作模型：直接编辑caseplan.json ，然后validate 。案例内容没有 CLI 驱动的变异路径。手动创作或编辑caseplan.json （或让智能体在uipath-maestro-case技能的 JSON 形状引用的指导下完成），然后运行uip maestro case validate进行检查。上述同级页面上记录的 read 动词（“cases get”、“stages list”、“tasks get”等）旨在帮助您在以这种方式创作计划时检查计划 — 它们不是写入 API 的一部分。
• 案例、BPMN 与流— 所有三个都是打包为.nupkg并共享 runtime 基元 ( process / job / instances / incidents / registry ) 的 Maestro 编排界面，但案例管理拥有自己的编排界面主资产为caseplan.json （加上生成的caseplan.json.bpmn ），其项目类型为CaseManagement project.uiproj operate.json与 BPMN 的.bpmn和 Flow 的.flow不同。
• 验证配置文件— validate根据创作的进度运行四个配置文件之一： skeleton （仅结构 — 节点、边缘、身份、类型）、 skeleton-v2 （框架以及 SLA/升级/entry-exit-rule）检查，仍会跳过任务内容）、 strict （每项检查，包括“无任务的阶段”、未解析的$xref标记和连接器上下文完整性（即已完成案例的门户））和默认的full配置文件（宽松，适用于部分创作或已打包的文件）。--sdd <path> 根据规范文档审核完整性，并包含 --strict。
• spec是一个规划工具，而非案例计划变异程序：它会获取一个 Integration Service 连接器活动或触发器的规范化说明（输入、输出、必填字段），以便您知道要在caseplan.json的任务/中放入哪些内容在编写触发器定义之前，先检查触发器定义。通过--activity-type-id / --connection-id查找所需的registry get-connector / get-connection值。

大纲

uip maestro case init <name> [--force] [--skip-solution-registration]
uip maestro case pack <project-path> <output-path> [-n, --name <name>] [-v, --version <version>] [package-metadata options...]
uip maestro case debug <project-path> [--folder-id <id>] [--poll-interval <ms>] [--login-validity <minutes>]
uip maestro case validate <file> [--skeleton | --skeleton-v2 | --strict] [--sdd <path>]
uip maestro case spec --type <activity|trigger> --activity-type-id <uuid> --connection-id <id> [--object-name <name>] [--skip-case-shape | --input-details <json>]

UIP Maestro 案例初始化

使用样板文件创建一个新的 案例项目: project.uiproj、operate.json、entry-points.json、bindings_v2.json、package-descriptor.json 和最小的 caseplan.json（仅在案例不存在时才写入 — 重新运行 init 从不会破坏编写的案例计划）。如果在现有解决方案外部运行，则系统会自动构建父 <name>Solution，并将案例项目嵌套在其中；如果在一个解决方案中运行，则项目将注册到该解决方案中。

参数

名称	必填	用途
<name>	是	案例项目名称。仅限字母、数字、下划线和连字符。

选项

长	值	描述
--force	标记	即使目标目录不为空，也进行初始化。写入文件而不清除现有内容。
--skip-solution-registration	标记	不要在相关解决方案中自动注册此项目。

示例

uip maestro case init my-case-project

数据形状（--输出 json）

{
  "Code": "CaseInit",
  "Data": {
    "Status": "Created successfully",
    "Path": "/workspace/my-case-project",
    "CasePlan": "/workspace/my-case-project/caseplan.json",
    "CasePlanStatus": "Created",
    "SolutionRegistration": { "Status": "Registered", "Solution": "...", "ProjectId": "..." },
    "AutoCreatedSolution": { "...": "present only when a parent solution was scaffolded" },
    "ProjectArtifacts": { "...": "present only when registered into a parent solution" },
    "NextSteps": "present only when SolutionRegistration.Instructions is set"
  }
}

CasePlanStatus"Created"在新框架上为"Preserved" ，而在保持现有caseplan.json 不变（在已编写的项目上重新运行init ）时为 。SolutionRegistration 始终存在 — 它的 Status 是 "NotInSolution"，而不是在不存在父解决方案时省略字段。

UIP Maestro 案例包

将案例项目目录打包到 .nupkg 文件中，该文件从项目根目录读取 caseplan.json。

参数

名称	必填	用途
<project-path>	是	案例项目目录的路径。
<output-path>	是	.nupkg 的输出目录。

选项

长	值	描述
-n, --name <name>	字符串	包名称。默认值：项目文件夹名称。
-v, --version <version>	字符串	包版本。默认 1.0.0。

同时接受此存储库的共享包元数据选项（ --repository-url / --repository-commit / --repository-branch / --repository-type 、 --release-notes 、 --project-url 、 --author 、 --description ）— 请参阅任何其他pack命令完整共享集的选项表格（例如uip maestro bpmn pack ），此命令以相同的方式注册。

示例

uip maestro case pack ./my-case-project ./dist --version 1.2.0

数据形状（--输出 json）

{
  "Code": "CasePack",
  "Data": {
    "Package": "my-case-project.1.2.0.nupkg",
    "Output": "./dist/my-case-project.1.2.0.nupkg"
  }
}

针对打包期间的架构错误（格式错误的 caseplan.json），在显示为故障之前，我们提供针对特定案例的指导原则 — 期待可操作的 Instructions，而不是原始解析器错误。

uip Maestro 案例调试

通过将案例项目上传到 Studio Web 并在其中运行调试会话来调试案例项目，案例管理没有仅限本地的调试模式（与其他一些 Maestro 调试命令不同）。

参数

名称	必填	用途
<project-path>	是	案例项目目录的路径。必须包含 project.uiproj。

选项

长	值	描述
--folder-id <id>	整数	Orchestrator 文件夹 ID (OrganizationUnitId)。省略时由自动检测。
--poll-interval <ms>	整数	轮询间隔（以毫秒为单位）。默认 2000。
--login-validity <minutes>	整数	在令牌过期前触发刷新的最短分钟数。默认 10。

需要带有可解析组织、租户和访问令牌的活动登录名 (uip login) — 快速失败，并显示特定消息，指明缺少的登录状态部分。

示例

uip maestro case debug ./my-case-project

数据形状（--输出 json）

{
  "Code": "CaseDebug",
  "Data": {
    "jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
    "runId": "d4e5f6a7-0000-0000-0000-000000000001",
    "finalStatus": "Completed",
    "solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
    "studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
    "elementExecutions": [
      { "elementId": "Stage_1", "status": "Completed" },
      { "elementId": "Stage_2", "status": "Completed" }
    ]
  }
}

密钥应保留其原生驼峰式命名法（而非帕斯卡命名法）——此有效负载旨在由评估检查器和 SDK 以编程方式读取，与 Flow 的调试命令和 registry get 使用的拆分命令相同。当 finalStatus 为 "Completed"/"Successful" 以外的任何值时，即使信封本身报告 Result: "Success"，命令也会非零退出 — 请检查脚本中的退出代码，而不仅仅是 Data 的存在。

uip Maestro 案例验证

根据案例管理的结构和业务规则验证案例管理 JSON 文件。

参数

名称	必填	用途
<file>	是	案例管理 JSON 文件的路径（通常是 caseplan.json）。

选项

长	描述
--skeleton	仅结构检查（节点、边缘、身份、类型）。跳过任务内容、SLA、升级和进入/退出规则 — 在创作的框架阶段非常有用。与 --skeleton-v2/--strict 冲突。
--skeleton-v2	框架检查以及 SLA、升级和进入/退出规则检查。仍会跳过任务内容。与 --skeleton/--strict 冲突。
--strict	每次检查，加上严格集合：没有任务、未解决的 $xref 标记、提升的 conditionExpression、形式参数/输出绑定形状和连接器上下文完整性的阶段。已完成案例的入口。与 --skeleton/--skeleton-v2 冲突。
--sdd <path>	根据给定的 SDD（规范文档）对案例计划的完整性进行审核，明确其声明的每个阶段、任务、任务类型、条件行、SLA、触发器和案例变量都必须存在。隐含 --strict。

省略所有四次运行默认的 full 配置文件：宽松，因此部分创作的文件或已打包的文件仍有效。

示例

uip maestro case validate case.json
uip maestro case validate case.json --skeleton
uip maestro case validate case.json --strict
uip maestro case validate case.json --sdd ./spec.md

数据形状（--输出 json）

{
  "Code": "CaseValidate",
  "Data": {
    "File": "case.json",
    "Status": "Valid",
    "Warnings": "2 warning(s):\n  - [stages[0].tasks[1]] ...",
    "Issues": [
      { "Code": "UNRESOLVED_REFERENCE", "Path": "stages[0].tasks[1]", "Message": "...", "Severity": "warning" }
    ]
  }
}

Profile: "strict"仅当传递了Data --strict（或--sdd ）时，才会将 添加到 。Warnings/Issues 仅当有效文件仍会生成警告时才会存在。失败时（Result: "Failure"，退出 1），Data.Issues 会以稳定的 Code、Path、Message 和 Severity 形式携带所有错误和警告 — 解析此数组，而不是人工可读的 Instructions（如果您正在驱动修复循环）文本。

uip Maestro 案例规范

生成规范化的 ConnectorTaskSpec — 生成可运行的 Integration Service 活动或在案例计划中触发器任务所需的一切。在本地类型缓存中查找类型，列出连接器的 Integration Service 连接，并提取 Integration Service 元数据。

选项

长	值	必填	描述
--type <type>	activity | trigger	是	要查找的类型缓存。
--activity-type-id <uuid>	UUID	是	Studio Web uiPathActivityTypeId。通过registry pull + 读取typecache-{activities,triggers}-index.json缓存文件，或registry get-connector查找它。
--connection-id <id>	UUID	是	连接 ID。列出包含registry get-connection --type typecache-{activities,triggers} --activity-type-id <uuid>候选对象。
--object-name <name>	字符串	否	覆盖类型缓存 objectName。对于类型缓存存储占位符（例如Data Service {tenantEntityName|folderEntityName}）— 选择一个真实的实体名称。
--skip-case-shape	标记	否	在响应中省略 caseShape (inputs[]/outputs[]/context[]) — 在只需要连接器合同时使用。与 --input-details 互斥。
--input-details <json>	JSON	否	预填充值并入生成的 caseShape。形状差异 --type：活动接受 {bodyParameters, queryParameters, pathParameters, filter}；触发器接受 {eventParameters, filter}。与 --skip-case-shape 互斥。

示例

# Curated connector activity (Send Email)
uip maestro case spec --type activity \
  --activity-type-id c7ce0a96-2091-3d94-b16f-706ebb1eb351 \
  --connection-id fc82e610-c454-4bc7-a1a5-b5aa529d1ba6

# Curated connector trigger (Email Received)
uip maestro case spec --type trigger \
  --activity-type-id 7dc57f24-894c-5ae2-a902-66056fa40609 \
  --connection-id fc82e610-c454-4bc7-a1a5-b5aa529d1ba6

数据形状（--输出 json）

{
  "Code": "ConnectorTaskSpec",
  "Data": {
    "specVersion": 1,
    "identity": {
      "target": "activity",
      "uiPathActivityTypeId": "c7ce0a96-2091-3d94-b16f-706ebb1eb351",
      "connectorKey": "uipath-microsoft-outlook365",
      "objectName": "send-mail-v2",
      "typecacheEntry": { "displayName": "Send Email" }
    },
    "operation": { "name": "POST", "verb": "create", "httpMethod": "POST", "path": "/hubs/productivity/send-mail-v2" },
    "inputs": { "bodyFields": [{ "name": "message.toRecipients", "required": true }] }
  }
}

触发器规范的 operation 形状不同（eventMode/事件名称，而不是 HTTP 动词/路径）— 请参阅上面的第二个示例。

相关内容

• registry — 发现要在案例计划中引用的资源，以及如何将任务输入绑定到变量。
• cases和stages — 检查案例计划元数据和阶段。
• tasks — 检查、丰富和描述任务定义。
• task-entry-conditions — 检查任务级别的进入规则。
• sla — 检查 SLA/升级规则。
• triggers 、 sticky-notes 、 edges — 检查触发器、画布备注和转换。
• 条件— 检查案例级和阶段级进入/退出条件规则。
• process 、 processes 、 job 、 instances 、 incidents — 部署并运行案例实例。
• uip maestro — BPMN 编排，同级界面。
• uip maestro flow — 流编排，另一个同级界面。

另请参阅

• Maestro 工具概述
• 全局选项
• 退出代码