maestro

latest

false

Maestro user guide

Establishing task I/O and write-back contracts

Overview

Task input/output (I/O) mapping defines the data contract between the Case Entity [Coming Soon] and each task in a case plan. Input mapping controls which Case Entity fields a task receives, and output mapping (write-back) controls which Case Entity fields a task enriches after execution. Establishing clear I/O contracts ensures that every task reads the correct data, writes results to the right fields, and keeps the Case Entity as a reliable single source of truth.

Audience: Intermediate — Automation Developers and Solution Architects building case plans in Studio Web.

Prerequisites

Access to Studio Web.
A case project created in Studio Web with at least one stage and one task defined. See Create a case project for setup instructions.
A Case Entity [Coming Soon] with fields defined — either as a native Data Fabric entity, a Virtual Data Object (VDO), or fields passed through a case trigger. See Case Entity overview for details.
Familiarity with the supported task types: Human action, RPA, API workflow, Execute Connector, AI Agent, Maestro Agentic Process, and Child Case.

Step 1: designing the case entity schema for I/O

Before mapping task inputs and outputs, define the Case Entity schema to distinguish between fields populated at case creation (input fields) and fields written by tasks during processing (output fields).

Identifying input fields

Input fields are populated when the case is created — through a Data Fabric trigger, a connector event, or an API call. These fields provide the starting context for all tasks.

Examples of input fields:

policyNumber — passed from the triggering system.
claimantName — supplied by the case creator.
lossDescription — free-text description provided at submission.

Identifying output fields

Output fields are written by tasks as the case progresses. Each output field should have a single owning task to prevent write collisions.

Examples of output fields:

validationResult — written by a "Validate Policy" connector task.
damageEstimate — written by an "Estimate Damage" agent task.
adjusterDecision — written by an "Adjuster Review" human task.

Documenting field ownership

Annotate each output field with the task responsible for writing it. While the schema does not enforce ownership at runtime, this documentation prevents accidental collisions during design.

{
  "entityName": "AutoInsuranceClaim",
  "fields": {
    "policyNumber":      { "type": "string",  "required": true },
    "claimantName":      { "type": "string",  "required": true },

    "policyValid":       { "type": "boolean", "writtenBy": "Validate Policy" },
    "extractedDetails":  { "type": "object",  "writtenBy": "Extract Details" },
    "damageEstimate":    { "type": "decimal", "writtenBy": "Estimate Damage" },
    "adjusterDecision":  { "type": "string",  "writtenBy": "Adjuster Review",
                           "enum": ["approve", "deny", "investigate_more"] },
    "payoutAmount":      { "type": "decimal", "writtenBy": "Calculate Payout" },
    "paymentReference":  { "type": "string",  "writtenBy": "Issue Payment" }
  }
}
{
  "entityName": "AutoInsuranceClaim",
  "fields": {
    "policyNumber":      { "type": "string",  "required": true },
    "claimantName":      { "type": "string",  "required": true },

    "policyValid":       { "type": "boolean", "writtenBy": "Validate Policy" },
    "extractedDetails":  { "type": "object",  "writtenBy": "Extract Details" },
    "damageEstimate":    { "type": "decimal", "writtenBy": "Estimate Damage" },
    "adjusterDecision":  { "type": "string",  "writtenBy": "Adjuster Review",
                           "enum": ["approve", "deny", "investigate_more"] },
    "payoutAmount":      { "type": "decimal", "writtenBy": "Calculate Payout" },
    "paymentReference":  { "type": "string",  "writtenBy": "Issue Payment" }
  }
}

Note:

Use namespaced field names (for example, validation.result vs. categorization.result) when multiple tasks produce structurally similar output. This avoids ambiguity and prevents the last-writer-wins problem.

Step 2: configuring input mapping for a task

Input mapping selects specific Case Entity fields and passes them as parameters to the task implementation (workflow, form, connector, or agent). This controls what data the task can see.

Opening the task configuration panel

In the Case Plan designer, select the target stage.
Select the task you want to configure.
Open the Input/Output section of the task configuration panel.

Mapping case entity fields to task parameters

In the Input section, select Add input mapping.
For each task parameter, choose the corresponding Case Entity field from the field picker.
Repeat for every parameter the task requires.

For example, a "Validate Receipts" task might use the following input mapping:

Task Parameter	Case Entity Field
`receipts`	`caseEntity.lineItems[*].receiptUrl`
`policyId`	`caseEntity.department`
`totalAmount`	`caseEntity.totalAmount`
`currency`	`caseEntity.currency`

Following the principle of least privilege

Pass only the fields the task needs. Avoid mapping the entire Case Entity [Coming Soon] to a single task. Scoping inputs reduces the risk of unintended data exposure and makes the task contract explicit.

Step 3: configuring output mapping (write-back) for a task

Output mapping takes the task's result and writes specific values back to the Case Entity [Coming Soon] . This is the write-back mechanism that enriches the central source of truth.

Defining output field mappings

In the same Input/Output section of the task configuration panel, locate the Output section.
Select Add output mapping.
For each result field the task produces, choose the target Case Entity field.

For example, a "Validate Receipts" task might use the following output mapping:

Case Entity Field	Task Output Field
`caseEntity.validationResult`	`taskOutput.validationResult`
`caseEntity.validationStatus`	`taskOutput.status`
`caseEntity.invalidReceipts`	`taskOutput.failedItems`

Ensuring one-writer-per-field

Assign each Case Entity output field to exactly one task. If two tasks write to the same field, the last writer wins and earlier data is lost.

Protecting read-only fields

Fields populated at case creation (for example, claimantName, policyNumber) should never appear as output targets. Do not map task outputs to these fields.

Step 4: verifying the write-back chain across stages

Once individual task mappings are in place, validate that the data flows correctly from one stage to the next through the Case Entity [Coming Soon] .

Tracing the data flow

Walk through each stage and confirm:

Task A in Stage 1 reads input fields from the Case Entity.
Task A writes its result to a specific Case Entity field via output mapping.
The Case Manager evaluates stage rules (rules first, Case Manager Agent fallback) using the updated Case Entity fields.
Task B in Stage 2 reads the field that Task A wrote, as its own input.

The pattern follows this sequence:

Task writes to entity → Entity state changes → Rules evaluate → Next stage activates → Downstream task reads updated entity

Validating rule dependencies

For each stage entry, complete, exit, and re-entry rule, confirm that the Case Entity field it references in its IF clause is populated by an upstream task's output mapping. If a rule references a field that no task writes to, the rule can never evaluate to true.

For example:

Stage Entry rule: IF caseEntity.adjusterDecision == "approve" — confirm the "Adjuster Review" task maps its decision output to caseEntity.adjusterDecision.
Stage Exit rule: IF caseEntity.policyValid == false — confirm the "Validate Policy" task maps its result to caseEntity.policyValid.

Step 5: handling re-entry scenarios

By default, every task in a re-entered stage re-executes and overwrites its previous output in the Case Entity. Use the per-task runOnlyOnce flag to opt specific tasks out of re-execution when their previous output is still valid.

Tasks that should re-execute on re-entry

Leave runOnlyOnce: false (the default) for tasks whose output may change after rework. These tasks re-run and overwrite their previous output in the Case Entity [Coming Soon].

Preserving outputs from tasks that should not re-run

Set runOnlyOnce: true on tasks whose previous output is still valid (for example, an initial categorization that does not depend on corrected data). These tasks are skipped on re-entry; their Case Entity fields remain unchanged.

Task	`runOnlyOnce`	Behavior on Re-entry
Validate Receipts	`false` (default)	Re-executes and overwrites `validationResult`
Categorize Expenses	`true`	Skipped; retains previous `categories` value
Check Policy Limits	`false` (default)	Re-executes and overwrites policy check output

Expected outcome

After completing these steps:

Every task in the case plan has explicit input mappings that scope the data it receives from the Case Entity [Coming Soon] .
Every task has explicit output mappings that write results back to designated Case Entity fields.
Each Case Entity output field has a single owning task, preventing write collisions.
Stage rules reference Case Entity fields that upstream tasks reliably populate.
Re-entry behavior is configured so that tasks produce fresh or preserved output as appropriate.
The Case Entity serves as the single source of truth throughout the entire case lifecycle.

Use case example

Scenario: Auto insurance claims processing with four stages — FNOL Intake, Investigation, Assessment, and Settlement.

Stage	Task	Input (from Case Entity [Coming Soon] )	Output (to Case Entity)
FNOL Intake	Validate Policy	`policyNumber`	`policyValid`
FNOL Intake	Extract Details	`lossDescription, photos`	`extractedDetails`
Investigation	Analyze Photos	`photos, vehicleInfo`	`photoAnalysis`
Investigation	Field Inspection	`claimId, vehicleInfo, lossDescription`	`fieldInspection`
Assessment	Estimate Damage	`photoAnalysis, fieldInspection, extractedDetails`	`damageEstimate`
Assessment	Adjuster Review	`damageEstimate, photoAnalysis, policeReport`	`adjusterDecision`
Settlement	Calculate Payout	`damageEstimate, policyNumber`	`payoutAmount`
Settlement	Issue Payment	`payoutAmount, claimantName`	`paymentReference`
Settlement	Notify Claimant	`claimantEmail, payoutAmount, paymentReference`	—

In this example, the "Estimate Damage" task in the Assessment stage consumes three fields written by upstream tasks in earlier stages (photoAnalysis, fieldInspection, extractedDetails). The Case Manager uses adjusterDecision — written by the "Adjuster Review" task — to evaluate the Settlement stage's Entry rule.

Code snippet

The following JSON illustrates a complete I/O mapping configuration for two tasks within the FNOL Intake stage:

{
  "stage": "FNOL Intake",
  "tasks": [
    {
      "name": "Validate Policy",
      "type": "connector",
      "required": true,
      "runOnlyOnce": false,
      "input": {
        "policyNumber": "caseEntity.policyNumber"
      },
      "output": {
        "caseEntity.policyValid": "taskOutput.isValid"
      }
    },
    {
      "name": "Extract Details",
      "type": "agent",
      "required": true,
      "runOnlyOnce": true,
      "input": {
        "description": "caseEntity.lossDescription",
        "photos": "caseEntity.photos"
      },
      "output": {
        "caseEntity.extractedDetails": "taskOutput.structuredData"
      }
    }
  ]
}
{
  "stage": "FNOL Intake",
  "tasks": [
    {
      "name": "Validate Policy",
      "type": "connector",
      "required": true,
      "runOnlyOnce": false,
      "input": {
        "policyNumber": "caseEntity.policyNumber"
      },
      "output": {
        "caseEntity.policyValid": "taskOutput.isValid"
      }
    },
    {
      "name": "Extract Details",
      "type": "agent",
      "required": true,
      "runOnlyOnce": true,
      "input": {
        "description": "caseEntity.lossDescription",
        "photos": "caseEntity.photos"
      },
      "output": {
        "caseEntity.extractedDetails": "taskOutput.structuredData"
      }
    }
  ]
}

Troubleshooting

Symptom	Likely Cause	Resolution
Downstream task receives empty or null input	Upstream task output mapping does not populate the expected Case Entity field	Verify that the upstream task's output mapping targets the correct Case Entity field name.
Stage rule never evaluates to true	The Case Entity field referenced in the rule is not written by any task	Add an output mapping from the responsible task to the referenced field.
Task overwrites data written by another task	Two tasks map their output to the same Case Entity field	Assign a unique Case Entity field to each task. Use namespaced field names to avoid collisions.
Re-entry produces stale results	Task has `runOnlyOnce` set to `true` but its output depends on corrected data	Set `runOnlyOnce` to `false` for tasks that must re-validate or re-process updated data.
Read-only field is overwritten during processing	A task output mapping targets a field that should be immutable (for example, `policyNumber`)	Remove the output mapping. Ensure input-only fields are never used as output targets.

Limitations

Variable filtering in the Monitoring view applies only to instances that run after you enable the filter. Existing instances are not retroactively filtered.
The writtenBy annotation in the entity schema is a design-time convention for documentation purposes. Maestro does not enforce single-writer rules at runtime.
Field-level access control on the Case Entity [Coming Soon] is not available in this preview release. All tasks with output mappings to a field can write to it.

Next steps

How to configure stage rules — Learn how to use Case Entity fields in entry, complete, exit, and re-entry rules.
How to configure re-entry behavior — Define which tasks re-execute when a case returns to a previously completed stage.
Case Entity overview — Understand the three out-of-the-box data objects (Case Entity [Coming Soon] , Case Documents, Case Comments) and how to bring data into a case.
Task types reference — Review all supported task types and their configuration options.

On this page

Overview
Prerequisites
Step 1: designing the case entity schema for I/O
Identifying input fields
Identifying output fields
Documenting field ownership
Step 2: configuring input mapping for a task
Opening the task configuration panel
Mapping case entity fields to task parameters
Following the principle of least privilege
Step 3: configuring output mapping (write-back) for a task
Defining output field mappings
Ensuring one-writer-per-field
Protecting read-only fields
Step 4: verifying the write-back chain across stages
Tracing the data flow
Validating rule dependencies
Step 5: handling re-entry scenarios
Tasks that should re-execute on re-entry
Preserving outputs from tasks that should not re-run
Expected outcome
Use case example
Code snippet
Troubleshooting
Limitations
Next steps

Was this page helpful?

PREVIOUSDefining case keys (system vs. external)

NEXTExit rules and early stage termination

Maestro user guide

Overview​

Prerequisites​

Step 1: designing the case entity schema for I/O​

Identifying input fields​

Identifying output fields​

Documenting field ownership​

Step 2: configuring input mapping for a task​

Opening the task configuration panel​

Mapping case entity fields to task parameters​

Following the principle of least privilege​

Step 3: configuring output mapping (write-back) for a task​

Defining output field mappings​

Ensuring one-writer-per-field​

Protecting read-only fields​

Step 4: verifying the write-back chain across stages​

Tracing the data flow​

Validating rule dependencies​

Step 5: handling re-entry scenarios​

Tasks that should re-execute on re-entry​

Preserving outputs from tasks that should not re-run​

Expected outcome​

Use case example​

Code snippet​

Troubleshooting​

Limitations​

Next steps​