# 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](maestro-case-management-component-dictionary.md#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`.

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

To end a case:

```json
{
  "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](how-to-establish-task-io-and-write-back-contracts.md#troubleshooting) — troubleshooting steps if tasks still don't trigger after fixing the output shape.
* [Case manager](maestro-case-management-component-dictionary.md#case-manager) — overview of rules-based vs. agentic Case Manager.