uip maestro case

Create, pack, debug, validate, and author Case Management projects using `uip maestro case`, the third Maestro orchestration surface alongside BPMN and Flow.

uip maestro case creates, packs, debugs, and authors Case Management projects — a third Maestro orchestration surface alongside BPMN and Flow. A case project models a long-running, human-driven unit of work as a case plan: a JSON document (caseplan.json) describing stages, tasks, SLAs, triggers, and the entry/exit conditions that move a case between stages — closer to a structured workflow-with-a-lifecycle than a linear process.

The tool ships as the separate @uipath/case-tool package, dynamically loaded by @uipath/maestro-tool under the case branch — every command here is invoked as uip maestro case <verb>, never as a standalone uip case.

This resource spans nine pages

• This page — concepts, and the project-lifecycle commands: init, pack, debug, validate, spec.
• registry — browse/search the automation-resource catalog a case wires tasks to, plus how to bind a task input to a variable.
• cases and stages — read the case-plan's top-level metadata and stage list.
• tasks — read, enrich, and describe task definitions within a stage.
• task-entry-conditions — read the rules that gate when a task becomes runnable.
• sla — read SLA/escalation rules.
• triggers, sticky-notes, edges — read case triggers, canvas annotations, and stage-to-stage transitions.
• case-exit-conditions, stage-entry-conditions, stage-exit-conditions — read the case-level and stage-level condition rules.
• process, processes, job, instances, incidents — deploy and run case instances on Orchestrator.

Conceitos

• The authoring model: edit caseplan.json directly, then validate. There is no CLI-driven mutation path for case content. Author or edit caseplan.json by hand (or have an agent do it, guided by the uipath-maestro-case skill's JSON-shape references), then run uip maestro case validate to check it. The read verbs documented on the sibling pages above (cases get, stages list, tasks get, etc.) exist to help you inspect the plan while authoring it this way — they are not part of a write API.
• Case vs. BPMN vs. Flow — all three are Maestro orchestration surfaces that pack to .nupkg and share runtime primitives (process/job/instances/incidents/registry), but Case Management's own primary asset is caseplan.json (plus a generated caseplan.json.bpmn), and its project type is CaseManagement in operate.json/project.uiproj — distinct from BPMN's .bpmn and Flow's .flow.
• Validation profiles — validate runs one of four profiles depending on how far along authoring is: skeleton (structure only — nodes, edges, identity, types), skeleton-v2 (skeleton plus SLA/escalation/entry-exit-rule checks, still skipping task content), strict (every check, including stage-with-no-tasks, unresolved $xref markers, and connector-context completeness — the finished-case gate), and the default full profile (lenient, for partially-authored or already-packed files). --sdd <path> audits completeness against a spec document and implies --strict.
• spec is a planning tool, not a case-plan mutator: it fetches a normalized description of one Integration Service connector activity or trigger (inputs, outputs, required fields) so you know what to put in caseplan.json's task/trigger definitions before you write them. Find the --activity-type-id/--connection-id values it needs via registry get-connector/get-connection.

Resumo

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 case init

Create a new Case project with boilerplate files: project.uiproj, operate.json, entry-points.json, bindings_v2.json, package-descriptor.json, and a minimal caseplan.json (only written if one doesn't already exist — re-running init never clobbers an authored case plan). If run outside an existing solution, a parent <name>Solution is scaffolded automatically and the case project is nested inside it; if run inside one, the project is registered into that solution instead.

Argumentos

Name	Required	Finalidade
<name>	sim	Case project name. Letters, numbers, underscores, and hyphens only.

Opções

Long	Valor	Description
--force	Bandeira	Initialize even if the target directory is not empty. Writes files without clearing existing contents.
--skip-solution-registration	Bandeira	Do not auto-register this project in the surrounding solution.

Exemplo

uip maestro case init my-case-project

Formato dos dados (--output 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 is "Created" on a fresh scaffold or "Preserved" when an existing caseplan.json was left untouched (re-running init on a project you've already authored). SolutionRegistration is always present — its Status is "NotInSolution" rather than the field being omitted when no parent solution exists.

uip maestro case pack

Pack a Case project directory into a .nupkg file, reading caseplan.json from the project root.

Argumentos

Name	Required	Finalidade
<project-path>	sim	Path to the Case project directory.
<output-path>	sim	Output directory for the .nupkg.

Opções

Long	Valor	Description
-n, --name <name>	String	Package name. Default: project folder name.
-v, --version <version>	String	Package version. Default 1.0.0.

Also accepts this repo's shared package-metadata options (--repository-url/--repository-commit/--repository-branch/--repository-type, --release-notes, --project-url, --author, --description) — see any other pack command's Options table (for example uip maestro pack) for the full shared set, which this command registers identically.

Exemplo

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

Formato dos dados (--output json)

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

A schema error during packing (a malformed caseplan.json) is enriched with case-specific guidance before being surfaced as a failure — expect actionable Instructions, not a raw parser error.

uip maestro case debug

Debug a case project by uploading it to Studio Web and running a debug session there — there is no local-only debug mode for Case Management (unlike some other Maestro debug commands).

Argumentos

Name	Required	Finalidade
<project-path>	sim	Path to the case project directory. Must contain project.uiproj.

Opções

Long	Valor	Description
--folder-id <id>	Número inteiro	Orchestrator folder ID (OrganizationUnitId). Auto-detected when omitted.
--poll-interval <ms>	Número inteiro	Polling interval in milliseconds. Default 2000.
--login-validity <minutes>	Número inteiro	Minimum minutes before token expiration to trigger a refresh. Default 10.

Requires an active login (uip login) with a resolvable organization, tenant, and access token — fails fast with a specific message naming whichever piece of login state is missing.

Exemplo

uip maestro case debug ./my-case-project

Formato dos dados (--output 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" }
    ]
  }
}

Keys are kept in their native camelCase (not PascalCased) — this payload is designed to be read programmatically by eval checkers and SDKs, matching the same carve-out used by Flow's debug command and registry get. The command exits non-zero when finalStatus is anything other than "Completed"/"Successful", even though the envelope itself reports Result: "Success" — check the exit code, not just the presence of Data, in scripts.

uip maestro case validate

Validate a case management JSON file against Case Management's structural and business rules.

Argumentos

Name	Required	Finalidade
<file>	sim	Path to the case management JSON file (typically caseplan.json).

Opções

Long	Description
--skeleton	Structural checks only (nodes, edges, identity, types). Skips task content, SLAs, escalations, and entry/exit rules — useful during the skeleton phase of authoring. Conflicts with --skeleton-v2/--strict.
--skeleton-v2	Skeleton checks plus SLA, escalation, and entry/exit rule checks. Still skips task content. Conflicts with --skeleton/--strict.
--strict	Every check, plus the strict set: a stage with no tasks, unresolved $xref markers, a hoisted conditionExpression, formal-argument/output-binding shapes, and connector-context completeness. The finished-case gate. Conflicts with --skeleton/--skeleton-v2.
--sdd <path>	Audit the caseplan for completeness against the given SDD (spec document) — every stage, task, task type, condition row, SLA, trigger, and case variable it declares must be present. Implies --strict.

Omitting all four runs the default full profile: lenient, so partially-authored or already-packed files still validate.

Exemplos

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

Formato dos dados (--output 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" is added to Data only when --strict (or --sdd) was passed. Warnings/Issues are present only when the valid file still produced warnings. On failure (Result: "Failure", exit 1), Data.Issues carries every error and warning with a stable Code, Path, Message, and Severity — parse this array rather than the human-readable Instructions text if you're driving a repair loop.

uip maestro case spec

Generate a normalized ConnectorTaskSpec — everything needed to construct a runnable Integration Service activity or trigger task inside a case plan. Looks up the type in the local TypeCache, lists Integration Service connections for the connector, and fetches Integration Service metadata.

Opções

Long	Valor	Required	Description
--type <type>	activity | trigger	sim	Which TypeCache to look up.
--activity-type-id <uuid>	UUID	sim	Studio Web uiPathActivityTypeId. Find it via registry pull + reading the typecache-{activities,triggers}-index.json cache file, or registry get-connector.
--connection-id <id>	UUID	sim	Connection ID. List candidates with registry get-connection --type typecache-{activities,triggers} --activity-type-id <uuid>.
--object-name <name>	String	não	Override the TypeCache objectName. Required for entity-typed curated triggers whose TypeCache stores a placeholder (e.g. Data Service {tenantEntityName|folderEntityName}) — pick a real entity name.
--skip-case-shape	Bandeira	não	Omit caseShape (inputs[]/outputs[]/context[]) from the response — use during planning when you only need the connector contract. Mutually exclusive with --input-details.
--input-details <json>	JSON	não	Pre-fill values folded into the generated caseShape. Shape differs by --type: activity accepts {bodyParameters, queryParameters, pathParameters, filter}; trigger accepts {eventParameters, filter}. Mutually exclusive with --skip-case-shape.

Exemplos

# 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

Formato dos dados (--output 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 }] }
  }
}

A trigger spec's operation shape differs (eventMode/event name instead of an HTTP verb/path) — see the second example above.

Relacionado

• registry — discover resources to reference in a case plan, and how to bind a task input to a variable.
• cases and stages — inspect case-plan metadata and stages.
• tasks — inspect, enrich, and describe task definitions.
• task-entry-conditions — inspect task-level entry rules.
• sla — inspect SLA/escalation rules.
• triggers, sticky-notes, edges — inspect triggers, canvas notes, and transitions.
• conditions — inspect case-level and stage-level entry/exit condition rules.
• process, processes, job, instances, incidents — deploy and run case instances.
• uip maestro — BPMN orchestration, the sibling surface.
• uip maestro flow — Flow orchestration, the other sibling surface.

Veja também

• Maestro tool overview
• Opções globais
• Códigos de saída