Sub use case node

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.

Parent workflow reaches Sub Use Case node

The parent workflow arrives at the Sub Use Case node with data in its variable store.

Input mapping

Data from the parent workflow is mapped to the child workflow’s input parameters.

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.

Child workflow executes

The child workflow runs through all its activities: agents, tools, conditions, human tasks, etc. The parent workflow waits.

Child workflow completes

When the child workflow finishes, its final output is captured.

Output mapping

The child workflow’s output is mapped back to the parent workflow’s variable store.

Parent workflow continues

The parent workflow resumes execution with access to the child workflow’s results.

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.

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:

{
  "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

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

Example: Calling a document verification workflow

{
  "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:

{
  "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:

{
  "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:

{
  "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:

Reusability

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.

Modularity

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”.

Separation of concerns

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.

Independent testing

Test complex workflow components independently before integrating.Example: Test the “Document Verification” workflow thoroughly in isolation, then integrate it into larger workflows with confidence.

Versioning and rollback

Update sub-workflows independently without changing parent workflows.Example: Deploy a new version of “Risk Assessment” workflow. Parent workflows automatically use the new version.

Don’t use sub use cases for:

Simple sequences

If it’s just a few nodes in sequence, keep them in the same workflow. Sub Use Cases add overhead.

One-time logic

If the logic is only used in one place and won’t be reused, don’t extract it to a sub-workflow.

Tight coupling

If the “sub” workflow is deeply coupled to the parent’s data structures, it’s not truly reusable. Keep it in the parent.

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.

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:

{
  "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

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

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.

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.

Handle errors gracefully

Sub-workflows should return structured error information, not just fail. Parent workflows can then decide how to handle specific errors.

Keep sub-workflows focused

Each sub-workflow should do one thing well. Don’t create mega sub-workflows that try to do everything.

Monitor sub-workflow performance

Track execution times, success rates, and costs for sub-workflows. Optimize frequently-used sub-workflows aggressively.

Test independently

Write tests for sub-workflows before integrating them into parent workflows. This catches issues early.

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.

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

Workflow overview

Understand how workflows compose into larger systems

Parallel execution

Call multiple sub-workflows simultaneously

Condition node

Conditionally call different sub-workflows

Memory system

Pass data between parent and child workflows

​Purpose

​How it works

​Configuration

​Select target use case

​Input mapping

​Output mapping

​Timeout and retry settings

​When to use sub use cases

​Use sub use cases for:

Reusability

Modularity

Separation of concerns

Independent testing

Versioning and rollback

​Don’t use sub use cases for:

Simple sequences

One-time logic

Tight coupling

​Examples

​Example 1: Reusable notification workflow

​Example 2: Document verification pipeline

​Example 3: Risk assessment module

​Example 4: Modular customer onboarding

​Best practices

​Advanced patterns

​Conditional sub-workflow selection

​Retry with fallback sub-workflow

​Chained sub-workflows

​Dynamic sub-workflow invocation

​Performance considerations

​Execution overhead

​Nested depth limits

​Parallel sub-workflow execution

​Next steps

Workflow overview

Parallel execution

Condition node

Memory system

Purpose

How it works

Configuration

Select target use case

Input mapping

Output mapping

Timeout and retry settings

When to use sub use cases

Use sub use cases for:

Don’t use sub use cases for:

Examples

Example 1: Reusable notification workflow

Example 2: Document verification pipeline

Example 3: Risk assessment module

Example 4: Modular customer onboarding

Best practices

Advanced patterns

Conditional sub-workflow selection

Retry with fallback sub-workflow

Chained sub-workflows

Dynamic sub-workflow invocation

Performance considerations

Execution overhead

Nested depth limits

Parallel sub-workflow execution

Next steps