Configures handler settings or AI user messages on flow steps. Supports both single-step and bulk pipeline-scoped operations.

Overview

The configure_flow_steps tool enables configuration of flow steps after creation:

1. Single Mode: Configure one specific flow step by ID
2. Bulk Mode: Configure all matching steps across all flows in a pipeline

Parameters

Validation Rules:

• *One of flow_step_id OR pipeline_id required
• **When pipeline_id provided, at least one of step_type or handler_slug required
• ***At least one of handler_config, user_message, or target_handler_slug required

Operational Modes

Single Mode

Provide flow_step_id to configure a specific step. If target_handler_slug is provided, the step will switch handlers.

Bulk Mode

Provide pipeline_id and filters (step_type and/or handler_slug) to update multiple flows at once. This is highly efficient for updating credentials, endpoints, or prompts across an entire pipeline.

Handler Switching & Field Mapping

When switching handlers (using target_handler_slug), the tool attempts to preserve existing configuration:

1. Explicit Mapping: Uses field_map to map old field names to new ones.
2. Auto-Mapping: Fields with identical names in both handlers are automatically preserved.
3. Cleanup: Fields that do not exist in the target handler and aren’t mapped are dropped.

Configuration Merge Logic

The tool uses a multi-layered merge approach for handler_config:

1. Mapped Base: Starts with existing config (mapped to new handler if switching).
2. Shared Config: handler_config is merged on top (applies to all targeted steps).
3. Per-Flow Config: In bulk mode, flow_configs allows overriding shared settings for specific flows (merges on top of Shared Config).

Bulk Mode: Shared vs. Per-Flow Config

{
  "pipeline_id": 42,
  "handler_slug": "rss",
  "handler_config": {
    "timeframe_limit": "24_hours"
  },
  "flow_configs": [
    {
      "flow_id": 101,
      "handler_config": { "feed_url": "https://site-a.com/rss" }
    },
    {
      "flow_id": 102,
      "handler_config": { "feed_url": "https://site-b.com/rss" }
    }
  ]
}

In this example, all matching steps get timeframe_limit: "24_hours", but each flow receives its specific feed_url.

Usage Examples

Single Mode: Switch Handler with Mapping

{
  "flow_step_id": "pipeline_step_123_456",
  "handler_slug": "old_handler",
  "target_handler_slug": "new_handler",
  "field_map": {
    "old_url_field": "new_source_field"
  },
  "handler_config": {
    "additional_new_setting": true
  }
}

Single Mode: Update Existing Handler Config

{
  "flow_step_id": "pipeline_step_123_456",
  "handler_config": {
    "taxonomy_category_selection": "skip"
  }
}

Bulk Mode: Update All WordPress Publish Steps in Pipeline

{
  "pipeline_id": 42,
  "handler_slug": "wordpress",
  "handler_config": {
    "taxonomy_category_selection": "skip"
  }
}

Bulk Mode: Update All Publish Steps by Type

{
  "pipeline_id": 42,
  "step_type": "publish",
  "handler_config": {
    "post_status": "draft"
  }
}

Bulk Mode: Update AI Prompts Across Pipeline

{
  "pipeline_id": 42,
  "step_type": "ai",
  "user_message": "Summarize the content in 2-3 sentences"
}

Response Format

Single Mode Response

{
  "success": true,
  "data": {
    "flow_step_id": "pipeline_step_123_456",
    "handler_updated": true,
    "handler_slug": "rss",
    "message": "Flow step configured successfully."
  }
}

Bulk Mode Response

{
  "success": true,
  "data": {
    "pipeline_id": 42,
    "flows_updated": 5,
    "steps_modified": 5,
    "details": [
      {"flow_id": 101, "flow_name": "Music Festival Feed", "flow_step_id": "ps_15_101"},
      {"flow_id": 102, "flow_name": "Food Festival Feed", "flow_step_id": "ps_15_102"}
    ],
    "message": "Updated 5 step(s) across 5 flow(s)."
  }
}

Handler Config Merge Behavior

The handler_config parameter merges into existing configuration rather than replacing it entirely. This allows targeted updates:

Existing config:

{
  "post_type": "post",
  "post_status": "publish",
  "taxonomy_category_selection": "15"
}

Update with:

{
  "handler_config": {
    "taxonomy_category_selection": "skip"
  }
}

Result:

{
  "post_type": "post",
  "post_status": "publish",
  "taxonomy_category_selection": "skip"
}

Integration Workflow

1. Query pipelines with api_query to find pipeline ID
2. Use configure_flow_steps with pipeline_id for bulk updates
3. Or use flow_step_id for targeted single-step configuration

Error Handling

Returns structured error responses for:

• Missing required parameters
• Invalid pipeline_id or flow_step_id
• No matching steps found for bulk criteria
• Handler configuration validation failures