> ## Documentation Index
> Fetch the complete documentation index at: https://helpcenter.magure.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub use case node

> Call other workflows as reusable components to build modular, maintainable AI systems

## Purpose

The **Sub Use Case node** calls another use case (workflow) as a step within the current workflow. This enables composition, reusability, and modularity. Build complex workflows by combining smaller, focused workflows.

Sub Use Case nodes are the key to building maintainable AI systems. Instead of duplicating logic across workflows, create reusable workflows that can be called from anywhere.

## How it works

When execution reaches a Sub Use Case node, it triggers a child workflow execution.

<Steps>
  <Step title="Parent workflow reaches Sub Use Case node">
    The parent workflow arrives at the Sub Use Case node with data in its variable store.
  </Step>

  <Step title="Input mapping">
    Data from the parent workflow is mapped to the child workflow's input parameters.
  </Step>

  <Step title="Child workflow starts">
    A new Temporal workflow execution starts for the child use case. This is a completely independent execution with its own variable store.
  </Step>

  <Step title="Child workflow executes">
    The child workflow runs through all its activities: agents, tools, conditions, human tasks, etc. The parent workflow waits.
  </Step>

  <Step title="Child workflow completes">
    When the child workflow finishes, its final output is captured.
  </Step>

  <Step title="Output mapping">
    The child workflow's output is mapped back to the parent workflow's variable store.
  </Step>

  <Step title="Parent workflow continues">
    The parent workflow resumes execution with access to the child workflow's results.
  </Step>
</Steps>

<Info>
  Sub Use Case executions are fully independent. Each has its own execution history, logs, and variable store. This isolation makes workflows easier to test, debug, and maintain.
</Info>

## Configuration

Configure a Sub Use Case node to call the right workflow with the right data.

### Select target use case

Choose which use case to execute from your project. The child use case must be in the **same project** as the parent workflow and must be active.

**Configuration:**

```json theme={null}
{
  "child_use_case_id": "uuid-of-child-use-case",
  "timeout_minutes": 60
}
```

**Example target use cases:**

* "Send Notification" — Reusable workflow for sending emails/Slack/SMS
* "Document Verification" — Standard KYC document verification
* "Risk Assessment" — Company-wide risk scoring logic
* "Compliance Check" — Standard compliance validation

### Input mapping

Map data from the parent workflow to the child workflow's expected inputs.

**Example: Calling a notification workflow**

```json theme={null}
{
  "recipient": "{{input.customer_email}}",
  "subject": "Analysis Complete",
  "body": "{{analysis_agent.summary}}",
  "priority": "normal",
  "attachments": [
    "{{report_generator.report_url}}"
  ]
}
```

**Example: Calling a document verification workflow**

```json theme={null}
{
  "document_url": "{{input.document_url}}",
  "document_type": "{{classifier.document_type}}",
  "verification_level": "standard",
  "customer_id": "{{input.customer_id}}"
}
```

**Variable references:**

You can reference any data from the parent workflow's variable store:

* Trigger inputs: `{{input.*}}`
* Previous activity outputs: `{{activity_name.*}}`
* Static values: Hard-coded strings, numbers, booleans

### Output mapping

Map the child workflow's output back to the parent workflow's variable store.

**Example output mapping:**

```json theme={null}
{
  "notification_sent": "{{sub_usecase.success}}",
  "notification_id": "{{sub_usecase.message_id}}",
  "notification_timestamp": "{{sub_usecase.sent_at}}"
}
```

**Accessing nested outputs:**

If the child workflow returns structured data:

```json theme={null}
{
  "verification_result": "{{sub_usecase}}",
  "is_verified": "{{sub_usecase.verified}}",
  "confidence_score": "{{sub_usecase.confidence}}",
  "extracted_data": "{{sub_usecase.extracted_fields}}"
}
```

### Timeout and retry settings

Configure how to handle child workflow failures:

**Timeout:**

* Set a maximum execution time for the child workflow
* If exceeded, the child workflow is cancelled and the parent can handle the timeout

**Retry policy:**

* Number of retry attempts if the child workflow fails
* Backoff strategy between retries
* Which error types trigger retries

**Example configuration:**

```json theme={null}
{
  "timeout": "5m",
  "retry": {
    "max_attempts": 3,
    "backoff": "exponential",
    "initial_interval": "10s"
  }
}
```

## When to use sub use cases

Sub Use Case nodes are powerful, but they add complexity. Use them strategically.

### Use sub use cases for:

<CardGroup cols={1}>
  <Card title="Reusability" icon="recycle">
    A workflow component is used by multiple parent workflows.

    **Example:** A "Send Notification" workflow called by 20 different workflows. Change notification logic once, all workflows benefit.
  </Card>

  <Card title="Modularity" icon="cubes">
    Break complex workflows into smaller, focused pieces that are easier to understand and maintain.

    **Example:** A "Customer Onboarding" workflow calls sub-workflows for "Document Verification", "Risk Assessment", and "Account Creation".
  </Card>

  <Card title="Separation of concerns" icon="layer-group">
    Different teams own different pieces of the workflow.

    **Example:** The compliance team owns the "Compliance Check" workflow, the finance team owns "Credit Assessment", and the main workflow orchestrates them.
  </Card>

  <Card title="Independent testing" icon="vial">
    Test complex workflow components independently before integrating.

    **Example:** Test the "Document Verification" workflow thoroughly in isolation, then integrate it into larger workflows with confidence.
  </Card>

  <Card title="Versioning and rollback" icon="code-branch">
    Update sub-workflows independently without changing parent workflows.

    **Example:** Deploy a new version of "Risk Assessment" workflow. Parent workflows automatically use the new version.
  </Card>
</CardGroup>

### Don't use sub use cases for:

<CardGroup cols={1}>
  <Card title="Simple sequences" icon="xmark">
    If it's just a few nodes in sequence, keep them in the same workflow. Sub Use Cases add overhead.
  </Card>

  <Card title="One-time logic" icon="xmark">
    If the logic is only used in one place and won't be reused, don't extract it to a sub-workflow.
  </Card>

  <Card title="Tight coupling" icon="xmark">
    If the "sub" workflow is deeply coupled to the parent's data structures, it's not truly reusable. Keep it in the parent.
  </Card>
</CardGroup>

<Tip>
  **Rule of thumb:** If you find yourself copying workflow segments between workflows, extract them to a Sub Use Case. If a workflow is getting too complex to understand at a glance, break it into smaller Sub Use Cases.
</Tip>

## Examples

Let's look at practical examples of Sub Use Case nodes.

### Example 1: Reusable notification workflow

**Scenario:** Multiple workflows need to send notifications via email, Slack, or SMS. Create one notification workflow, use it everywhere.

**Sub Use Case: "Send Notification"**

```
Workflow: Send Notification
Inputs:
  - recipient (email, slack_user_id, or phone)
  - channel (email, slack, sms)
  - subject/title
  - body/message
  - priority (low, normal, high, urgent)
  - attachments (optional)

Activities:
  1. Condition: channel == "email"
     ├─ True: Tool: "Send email via Gmail"
     └─ False: Condition: channel == "slack"
         ├─ True: Tool: "Send Slack message"
         └─ False: Tool: "Send SMS"

  2. Tool: "Log notification sent"

  3. Condition: priority == "urgent"
     ├─ True: Tool: "Send follow-up notification after 5 min"
     └─ False: Skip

Outputs:
  - success: boolean
  - message_id: string
  - sent_at: timestamp
```

**Parent workflows call it:**

```json theme={null}
{
  "node_type": "sub_usecase",
  "target": "Send Notification",
  "input": {
    "recipient": "{{customer_email}}",
    "channel": "email",
    "subject": "Your document has been processed",
    "body": "{{report_summary}}",
    "priority": "normal"
  }
}
```

**Benefits:**

* One place to update notification logic
* Consistent notification handling across all workflows
* Easy to add new notification channels (Teams, WhatsApp, etc.)
* Centralized logging and monitoring

### Example 2: Document verification pipeline

**Scenario:** Multiple workflows need to verify documents. Standardize the verification process.

**Sub Use Case: "Document Verification"**

```
Workflow: Document Verification
Inputs:
  - document_url: URL to document image
  - document_type: passport, emirates_id, trade_license, etc.
  - verification_level: basic, standard, enhanced
  - customer_id: for audit trail

Activities:
  1. Agent: Vision model extracts data from document

  2. Agent: Validates document authenticity
     - Check for signs of tampering
     - Validate security features
     - Check expiry date

  3. Condition: verification_level == "enhanced"
     ├─ True: Tool: Call external verification API
     └─ False: Skip

  4. Agent: Generate verification report

  5. Tool: Log verification to compliance database

Outputs:
  - verified: boolean
  - confidence: number (0-1)
  - extracted_data: object
  - verification_report: string
  - issues_found: array
```

**Parent workflow: Customer Onboarding**

```
Workflow: Customer Onboarding
  1. Collect customer documents (Trigger)

  2. Parallel Node:
     ├─ Sub Use Case: "Document Verification"
     │  Input: {document_url: passport_url, document_type: "passport"}
     │
     ├─ Sub Use Case: "Document Verification"
     │  Input: {document_url: emirates_id_url, document_type: "emirates_id"}
     │
     └─ Sub Use Case: "Document Verification"
        Input: {document_url: utility_bill_url, document_type: "proof_of_address"}

  3. Agent: Cross-validate data consistency

  4. Condition: All verified
     ├─ True: Continue onboarding
     └─ False: Request additional documents
```

**Benefits:**

* Consistent verification across all document types
* Easy to update verification logic globally
* Independent testing of verification workflow
* Reusable across onboarding, KYC updates, re-verification, etc.

### Example 3: Risk assessment module

**Scenario:** Multiple workflows need risk assessment. Standardize risk scoring.

**Sub Use Case: "Risk Assessment"**

```
Workflow: Risk Assessment
Inputs:
  - entity_id: customer, transaction, or document ID
  - entity_type: customer, transaction, document
  - assessment_type: kyc, transaction, credit, compliance
  - context: additional context for assessment

Activities:
  1. Tool: Fetch entity data from database

  2. Parallel Node:
     ├─ Agent: Financial risk analysis
     ├─ Agent: Compliance risk analysis
     ├─ Agent: Reputational risk analysis
     └─ Agent: Operational risk analysis

  3. Agent: Synthesize risk scores into overall assessment

  4. Condition: risk_score > 0.8
     ├─ True: Human Task: "High-risk review required"
     └─ False: Auto-approve

  5. Tool: Store risk assessment in database

Outputs:
  - risk_score: number (0-1)
  - risk_level: low, medium, high, critical
  - risk_factors: array of identified risks
  - recommendation: approve, review, reject
  - assessment_report: detailed report
```

**Multiple parent workflows use it:**

**Workflow 1: New Customer Onboarding**

```
Sub Use Case: "Risk Assessment"
Input: {entity_id: customer_id, entity_type: "customer", assessment_type: "kyc"}
```

**Workflow 2: Large Transaction Processing**

```
Sub Use Case: "Risk Assessment"
Input: {entity_id: transaction_id, entity_type: "transaction", assessment_type: "transaction"}
```

**Workflow 3: Credit Application**

```
Sub Use Case: "Risk Assessment"
Input: {entity_id: application_id, entity_type: "customer", assessment_type: "credit"}
```

**Benefits:**

* Consistent risk assessment methodology
* Single source of truth for risk logic
* Easy to update risk models globally
* Centralized compliance and audit trail

### Example 4: Modular customer onboarding

**Scenario:** Customer onboarding is complex. Break it into focused sub-workflows.

**Main Workflow: Customer Onboarding**

```
Workflow: Customer Onboarding
  1. Sub Use Case: "Collect Customer Information"
     → Interactive form collection or API input

  2. Parallel Node:
     ├─ Sub Use Case: "Document Verification"
     ├─ Sub Use Case: "Background Check"
     └─ Sub Use Case: "Credit Assessment"

  3. Sub Use Case: "Risk Assessment"
     Input: Outputs from step 2

  4. Condition: risk_level acceptable
     ├─ True: Sub Use Case: "Create Account"
     └─ False: Sub Use Case: "Send Rejection Notice"

  5. Sub Use Case: "Welcome Email and Next Steps"

  6. Sub Use Case: "Update CRM"
```

Each sub-workflow is independently:

* Developed by the responsible team
* Tested in isolation
* Versioned and deployed
* Monitored and optimized

**Benefits:**

* Clear separation of concerns
* Teams work independently
* Easy to test and debug
* Flexible to update individual components

## Best practices

<AccordionGroup>
  <Accordion title="Design for reusability">
    When creating a workflow that might become a sub-workflow, design it to be reusable:

    * Clear, well-defined inputs
    * Predictable outputs
    * No hidden dependencies on external state
    * Comprehensive error handling
  </Accordion>

  <Accordion title="Use semantic versioning">
    Version your sub-workflows (v1.0, v1.1, v2.0). Parent workflows can specify which version to use, enabling gradual rollout of changes.
  </Accordion>

  <Accordion title="Document inputs and outputs">
    Clearly document what inputs the sub-workflow expects and what outputs it produces. This is the "contract" between parent and child.
  </Accordion>

  <Accordion title="Handle errors gracefully">
    Sub-workflows should return structured error information, not just fail. Parent workflows can then decide how to handle specific errors.
  </Accordion>

  <Accordion title="Keep sub-workflows focused">
    Each sub-workflow should do one thing well. Don't create mega sub-workflows that try to do everything.
  </Accordion>

  <Accordion title="Monitor sub-workflow performance">
    Track execution times, success rates, and costs for sub-workflows. Optimize frequently-used sub-workflows aggressively.
  </Accordion>

  <Accordion title="Test independently">
    Write tests for sub-workflows before integrating them into parent workflows. This catches issues early.
  </Accordion>
</AccordionGroup>

<Warning>
  Sub Use Case nodes create parent-child workflow relationships. Be careful not to create circular dependencies (Workflow A calls B, B calls A). MagOneAI will detect and prevent this, but design workflows to avoid it.
</Warning>

## Advanced patterns

### Conditional sub-workflow selection

Choose which sub-workflow to call based on data:

```
Condition: document_type == "passport"
  ├─ True: Sub Use Case: "Passport Verification"
  └─ False: Condition: document_type == "emirates_id"
      ├─ True: Sub Use Case: "Emirates ID Verification"
      └─ False: Sub Use Case: "Generic Document Verification"
```

### Retry with fallback sub-workflow

Try a primary sub-workflow, fall back to an alternative on failure:

```
Sub Use Case: "Premium Verification Service"
  (with retry: max_attempts = 2)

→ Condition: verification_successful
    ├─ True: Continue
    └─ False: Sub Use Case: "Standard Verification Service"
```

### Chained sub-workflows

Call sub-workflows in sequence, each building on the previous:

```
Sub Use Case: "Data Collection"
  → Output: raw_data

Sub Use Case: "Data Enrichment"
  → Input: {{data_collection.raw_data}}
  → Output: enriched_data

Sub Use Case: "Data Validation"
  → Input: {{data_enrichment.enriched_data}}
  → Output: validated_data

Sub Use Case: "Data Storage"
  → Input: {{data_validation.validated_data}}
```

### Dynamic sub-workflow invocation

Use ForEach to call a sub-workflow for each item in a collection:

```
ForEach: items in {{input.documents}}
  → Sub Use Case: "Process Document"
    Input: {document_url: {{foreach.current_item}}}
```

## Performance considerations

### Execution overhead

Each Sub Use Case node adds overhead:

* Temporal workflow creation
* Input/output serialization
* Separate execution history

**Impact:** \~100-200ms overhead per sub-workflow invocation

**Mitigation:** Use sub-workflows for substantial work (multi-step processes), not single activities.

### Nested depth limits

Avoid deeply nested sub-workflows (workflow calls workflow calls workflow calls...).

**Recommended:** Max 3 levels of nesting
**Absolute maximum:** 5 levels

Deep nesting makes workflows hard to debug and may hit Temporal limits.

### Parallel sub-workflow execution

When using Parallel nodes to call multiple sub-workflows, each executes independently:

```
Parallel Node:
  ├─ Sub Use Case A (1 minute)
  ├─ Sub Use Case B (2 minutes)
  └─ Sub Use Case C (1.5 minutes)

Total time: ~2 minutes (not 4.5 minutes)
```

This is efficient for independent operations.

## Next steps

<CardGroup cols={2}>
  <Card title="Workflow overview" icon="diagram-project" href="/workflows/overview">
    Understand how workflows compose into larger systems
  </Card>

  <Card title="Parallel execution" icon="code-branch" href="/workflows/parallel-node">
    Call multiple sub-workflows simultaneously
  </Card>

  <Card title="Condition node" icon="code-branch" href="/workflows/condition-node">
    Conditionally call different sub-workflows
  </Card>

  <Card title="Memory system" icon="database" href="/workflows/memory">
    Pass data between parent and child workflows
  </Card>
</CardGroup>