Case Manager input and output contract

Look up the exact input and output shape required by the Case Manager, including the caseManagerDecisions and caseCurrentExecutionState objects.

	Maestro Case	Maestro BPMN	Maestro Flow
Content applies to	✅	❌	❌

Overview

The Case Manager orchestrates a case using rules, an agent, or both together. Whichever mode you use, the Case Manager task must accept and return specific data shapes. This page documents that contract. Case Manager tasks fail silently (the run reports as successful, but no tasks execute and no stages transition) when the output does not match this contract exactly.

For a conceptual overview of rules-based vs. agentic orchestration, see Case manager in the component dictionary.

Input contract

Field	Type	Populated by	Description
caseCurrentExecutionState	Object	Maestro (automatic)	The current state of the case: which stages are active, exited, or complete, which tasks are running or completed, and current case variable values.
caseRulesDecisions	Object	Maestro (automatic, rules-based or hybrid setups only)	The rules engine's own recommended decisions, evaluated before the agent runs. Same shape as caseManagerDecisions, below.

Note:

Do not map a value to either input yourself. As long as the Case Manager task declares an input with one of these exact names, Maestro populates it automatically on every run.

When to use caseCurrentExecutionState

Reference caseCurrentExecutionState when your agent's decision depends on case history — for example, "only send the follow-up task if the review task already completed." It includes:

• Which stages have been entered, exited, or completed
• Which tasks are running or completed
• Case variable values, grouped by stage

When to use caseRulesDecisions

Reference caseRulesDecisions only if your case plan combines deterministic rules with an agent. In that setup, the rules engine runs first and produces its own recommended decisions — the agent can use that as a starting point and override or extend it. If your case plan uses the agent alone, you don't need this input.

Output contract

The Case Manager task must return a single output field named caseManagerDecisions. This field controls every orchestration decision for the case.

caseManagerDecisions key	Type	Description
tasksToRun	Array of objects	Tasks to trigger next. Each object has one field: taskName.
tasksToCancel	Array of objects	Running tasks to cancel. Each object has one field: identifier, matching the task's identifier from caseCurrentExecutionState.
stagesEntered	Array of objects	Stages to activate. Each object has one field: stageName.
stagesExited	Array of objects	Stages to terminate early. Each object has one field: stageName.
stagesCompleted	Array of objects	Stages to mark complete. Each object has one field: stageName.
caseResolution	Object	Ends the case. Contains type, set to completed or exited.

Every key is optional — include only the decisions relevant to the current event. For example, a decision that only starts a task does not need to include stagesEntered or caseResolution.

{
  "caseManagerDecisions": {
    "tasksToRun": [
      { "taskName": "Task 1" },
      { "taskName": "Task 2" }
    ],
    "stagesCompleted": [
      { "stageName": "Intake" }
    ]
  }
}

To end a case:

{
  "caseManagerDecisions": {
    "caseResolution": {
      "type": "completed"
    }
  }
}

Common mistake

A plain array of task names — for example ["Task 1", "Task 2"] — is not a valid output. The Case Manager silently takes no action instead of raising a validation error. Always nest the array under caseManagerDecisions.tasksToRun, with each entry as an object containing taskName.

Related resources

• Establishing task I/O and write-back contracts — troubleshooting steps if tasks still don't trigger after fixing the output shape.
• Case manager — overview of rules-based vs. agentic Case Manager.