Mock Chains

Define sequences of automated steps that execute when specific HTTP requests match. Mock chains enable multi-step workflows, stateful interactions, and complex test scenarios on your mock simulations.

Prerequisites

• An existing mock simulation
• Understanding of routes and mock state (environments/variables)
• Optional: Knowledge of state management in SureStage

Understanding Mock Chains

Mock chains define workflows triggered by HTTP requests:

Components:

• Trigger - HTTP method + path pattern that activates the chain
• Trigger Conditions (optional) - Additional conditions from request body
• Steps - Ordered sequence of actions to execute
• Step Delays - Optional delays between steps
• Concurrency Control - Limit simultaneous executions
• Timeout - Maximum execution time before auto-cancel

Step Actions:

Action	Purpose	Example
set_state	Update mock state (environments/variables)	Set status to "approved"
modify_route	Change a route's response temporarily	Flip from 200 to 500
fire_webhook	Send webhook to external URL	Notify consumer of state change
reset_route	Reset route to original response	Restore original behavior
log_event	Log event for debugging	Record workflow milestone

Creating a Chain

Access Chain Configuration

1. Open your mock simulation
2. Click Workflows or Chains tab
3. Click Create Chain or New Workflow

Define Trigger

Specify what request activates the chain:

{
  "name": "Application Approval Workflow",
  "description": "When application is submitted, approve after delay",
  "trigger_method": "POST",
  "trigger_path": "/api/applications",
  "trigger_conditions": {
    "body": {
      "type": "premium"
    }
  },
  "max_concurrent_executions": 1,
  "execution_timeout_ms": 30000
}

Trigger Fields:

• name - Human-readable chain name
• description - What this chain does
• trigger_method - HTTP method (GET, POST, PUT, PATCH, DELETE)
• trigger_path - URL path (supports wildcards)
• trigger_conditions - Optional request matching rules
• max_concurrent_executions - Concurrent execution limit (1-10, default 1)
• execution_timeout_ms - Max runtime before auto-cancel (default 30000ms)

Add Chain Steps

Add actions to execute sequentially:

{
  "steps": [
    {
      "action": "log_event",
      "delay_ms": 0,
      "config": {
        "eventType": "application_received",
        "message": "Application received and queued for processing"
      }
    },
    {
      "action": "set_state",
      "delay_ms": 2000,
      "config": {
        "collection_id": "applications",
        "data": {
          "id": "app-123",
          "status": "in_review"
        }
      }
    },
    {
      "action": "set_state",
      "delay_ms": 5000,
      "config": {
        "collection_id": "applications",
        "data": {
          "id": "app-123",
          "status": "approved"
        }
      }
    },
    {
      "action": "fire_webhook",
      "delay_ms": 0,
      "config": {
        "url": "https://external-system.com/webhooks/approval",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer webhook-key"
        },
        "body": {
          "application_id": "app-123",
          "status": "approved"
        }
      }
    }
  ]
}

Step Fields:

• action - Type of action to perform
• delay_ms - Wait time before executing step (0-300000ms)
• config - Action-specific configuration

Step Configuration by Action Type

set_state Action

Update mock state (environments or variables):

{
  "action": "set_state",
  "delay_ms": 1000,
  "config": {
    "collection_id": "users",
    "data": {
      "id": "user-123",
      "email": "user@example.com",
      "verified": true
    }
  }
}

Or update simulation variables:

{
  "action": "set_state",
  "config": {
    "variable": "current_user_id",
    "value": "user-123"
  }
}

modify_route Action

Temporarily change a route's behavior:

{
  "action": "modify_route",
  "delay_ms": 0,
  "config": {
    "route_id": "get-status-route-id",
    "response_override": {
      "statusCode": 500,
      "body": {
        "error": "System error occurred"
      }
    },
    "duration_ms": 5000
  }
}

The route behavior reverts to normal after duration_ms expires.

fire_webhook Action

Send HTTP request to external system:

{
  "action": "fire_webhook",
  "delay_ms": 0,
  "config": {
    "url": "https://external-service.com/webhook",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer token"
    },
    "body": {
      "event": "order_processed",
      "orderId": "order-123"
    },
    "timeout_ms": 5000
  }
}

reset_route Action

Restore a route to original response:

{
  "action": "reset_route",
  "delay_ms": 0,
  "config": {
    "route_id": "modified-route-id"
  }
}

Use after modify_route to restore normal behavior.

log_event Action

Record event for debugging and auditing:

{
  "action": "log_event",
  "delay_ms": 0,
  "config": {
    "eventType": "workflow_milestone",
    "message": "Moving to next processing stage",
    "metadata": {
      "recordId": "rec-123",
      "previousStatus": "pending"
    }
  }
}

Managing Chains

List Chains

View all chains for a simulation:

1. Open simulation
2. Click Chains tab
3. See list with:
   • Chain name and description
   • Trigger method/path
   • Enabled/disabled status
   • Execution statistics

Get Chain Details

View full chain configuration:

1. Click chain name
2. See trigger configuration
3. View step sequence
4. Check execution history

Update Chain

Modify chain configuration:

1. Open chain
2. Click Edit
3. Update trigger, steps, or settings
4. Click Save

Changes take effect immediately for new executions.

Delete Chain

Remove a chain permanently:

1. Open chain
2. Click Delete or Remove
3. Confirm deletion
4. Chain no longer triggers on matching requests

Enabling and Disabling Chains

Enable Chain

Activate a chain to trigger on matching requests:

1. Open chain
2. Click Enable or toggle switch
3. Chain begins processing matching requests

Disable Chain

Pause chain without deleting:

1. Open chain
2. Click Disable or toggle switch
3. Matching requests no longer trigger the chain
4. Running executions continue to completion

Triggering Chains

Automatic Trigger

Chains trigger automatically when matching request arrives:

curl -X POST https://instance.surestage.io/api/applications \
  -H "Content-Type: application/json" \
  -d '{"type": "premium"}'

If trigger conditions match, the chain automatically executes.

Manual Trigger

Manually start chain execution:

1. Open chain details
2. Click Trigger or Start Execution
3. Optionally provide trigger data:

{
  "triggeredBy": "manual",
  "context": {
    "userId": "user-123",
    "action": "test"
  }
}

4. Click Execute
5. Chain begins running

Monitoring Chain Executions

View Execution History

See all chain executions:

1. Open simulation
2. Click Chains > Executions tab
3. View paginated list of executions with:
   • Timestamp
   • Chain name
   • Trigger type (automatic/manual)
   • Status (running, completed, failed)
   • Duration
   • Result

Get Execution Details

View specific execution progress:

1. Click execution in list
2. See:
   • Current step (0-based index)
   • Step status (pending, running, completed)
   • Step output/results
   • Any error messages
   • Total execution time
   • Step timings

Example execution detail:

{
  "executionId": "exec-abc123",
  "chainId": "chain-xyz",
  "status": "completed",
  "totalDuration": 8000,
  "steps": [
    {
      "index": 0,
      "action": "log_event",
      "status": "completed",
      "duration": 5,
      "output": "Event logged: application_received"
    },
    {
      "index": 1,
      "action": "set_state",
      "status": "completed",
      "duration": 10,
      "output": "State updated: applications.status=in_review"
    },
    {
      "index": 2,
      "action": "set_state",
      "status": "completed",
      "duration": 8,
      "output": "State updated: applications.status=approved"
    },
    {
      "index": 3,
      "action": "fire_webhook",
      "status": "completed",
      "duration": 1200,
      "output": "Webhook delivered successfully (status 200)"
    }
  ]
}

Cancel Running Execution

Stop a chain execution in progress:

1. Click running execution
2. Click Cancel or Stop
3. Execution stops at current step
4. Remaining steps don't execute
5. Status shows "failed" or "cancelled"

Common Chain Patterns

Approval Workflow

Simulate multi-stage approval process:

{
  "name": "Approval Workflow",
  "trigger_method": "POST",
  "trigger_path": "/api/requests",
  "steps": [
    {
      "action": "set_state",
      "delay_ms": 0,
      "config": {
        "collection_id": "requests",
        "data": { "id": "req-1", "status": "pending" }
      }
    },
    {
      "action": "set_state",
      "delay_ms": 3000,
      "config": {
        "collection_id": "requests",
        "data": { "id": "req-1", "status": "approved" }
      }
    }
  ]
}

Error Simulation

Simulate failure then recovery:

{
  "name": "Failure Then Recovery",
  "trigger_method": "GET",
  "trigger_path": "/api/status",
  "steps": [
    {
      "action": "modify_route",
      "delay_ms": 0,
      "config": {
        "route_id": "status-route",
        "response_override": { "statusCode": 500 },
        "duration_ms": 3000
      }
    },
    {
      "action": "reset_route",
      "delay_ms": 3000,
      "config": { "route_id": "status-route" }
    }
  ]
}

External Notification

Notify external systems of state changes:

{
  "name": "Notify External System",
  "trigger_method": "POST",
  "trigger_path": "/api/orders",
  "steps": [
    {
      "action": "log_event",
      "config": { "eventType": "order_created" }
    },
    {
      "action": "fire_webhook",
      "delay_ms": 0,
      "config": {
        "url": "https://webhook.example.com/order-created",
        "method": "POST",
        "body": { "event": "order_created", "orderId": "order-123" }
      }
    }
  ]
}

Troubleshooting

Chain Not Triggering

• Verify chain is enabled (toggle switch)
• Check trigger method matches (GET, POST, etc.)
• Verify trigger path matches request path
• If trigger_conditions set, ensure request data matches
• Check execution history for error messages

Step Not Executing

• Verify step delay is not excessively long
• Check step configuration is valid JSON
• Ensure collection/route IDs are correct
• Look at execution detail for specific error

Webhook Not Firing

• Verify external URL is reachable
• Check Authorization header if required
• Review webhook timeout setting
• Check firewall/network rules
• Look at execution logs for response status

Execution Timeout

• Increase execution_timeout_ms if steps need more time
• Reduce number of steps or delays
• Simplify step configurations
• Check for infinite loops in logic

API Reference

Chain Management Endpoints

Method	Path	Description
GET	/instances/:id/chains	List chains
POST	/instances/:id/chains	Create chain
GET	/instances/:id/chains/:chainId	Get chain details
PATCH	/instances/:id/chains/:chainId	Update chain
DELETE	/instances/:id/chains/:chainId	Delete chain
POST	/instances/:id/chains/:chainId/enable	Enable chain
POST	/instances/:id/chains/:chainId/disable	Disable chain
POST	/instances/:id/chains/:chainId/trigger	Trigger manually

Execution Endpoints

Method	Path	Description
GET	/instances/:id/chains/executions	List executions
GET	/instances/:id/chains/executions/:execId	Get execution details
POST	/instances/:id/chains/executions/:execId/cancel	Cancel execution

Next Steps

• Environments - Use environments in chain state updates
• Flows - Create multi-simulation workflows
• Analytics - Monitor chain execution patterns
• Protocol Editors - Visual editors for webhook and other protocol types