Creating Flows

fyrn offers three ways to create integration flows: AI-assisted generation, templates, and manual YAML authoring. All three produce the same YAML DSL output.

AI Assist

The fastest way to create a flow. Describe what you need in natural language.

Via CLI

fyrn flow create "Sync new Shopify orders to NetSuite as sales orders"

The AI generates a complete YAML flow config. You review it, edit if needed, and confirm to save.

# With error handling preference
fyrn flow create "Forward webhook events to Slack" --error-handling conservative

Via MCP

AI agents can create flows through the MCP server:

{
  "name": "create_flow",
  "arguments": {
    "description": "Sync orders from Shopify to NetSuite whenever a new order is placed",
    "source_hint": "Shopify webhook",
    "target_hint": "NetSuite REST API"
  }
}

Via interactive mode

fyrn
# > Create a flow that takes Shopify orders and sends them to my SAP system

When you run fyrn flow create, the following happens behind the scenes:

1. Connector catalog lookup — fyrn resolves the connectors mentioned in your description against the installed connector catalog. Each connector’s schema (endpoints, auth methods, field types) is included as context.
2. Prompt construction — Your description is combined with the DSL specification, connector schemas, and any flags you passed (e.g., --error-handling conservative) into a structured prompt.
3. YAML generation — The AI produces a complete flow YAML config, including source/target configuration, field mappings, transforms, and error handling.
4. Validation — The generated YAML is parsed and validated against the DSL schema before it is shown to you. If validation fails, the AI automatically retries with the error details as feedback.

The result is a valid, deployable flow config — but you should always review the mappings and test with sample data before deploying to production.

---

Templates

Templates are pre-built flow configurations for common integration patterns. Each template includes a working YAML config with sensible defaults for source, target, mapping, and error handling. After initializing from a template, you customize the connector credentials and field mappings for your specific use case.

Templates provide pre-built flow configurations for common integration patterns:

# List available templates
fyrn adapters templates

# Initialize from a template
fyrn init --template shopify-to-erp

Common templates

The template catalog is expanding. Currently available templates:

• shopify-to-erp — Shopify orders to ERP system
• webhook-to-slack — Forward webhooks to Slack notifications
• csv-import — Batch CSV import with error handling
• api-to-api — Generic REST API sync

---

Manual YAML

Write flow YAML by hand for full control. Start with the DSL specification.

Minimal flow

flow: my-webhook-handler
version: 1
source:
  connector: incoming-webhook
  trigger: webhook
target:
  connector: my-api
  endpoint: /api/data
  method: POST
mapping:
  id: source.id
  name: source.name

Validate before deploying

fyrn flow test flows/my-flow.yaml --sample-data test.json

The test command parses the YAML, compiles the flow, and runs the mapping against your sample data. Fix any errors before deploying.

---

Editing existing flows

Pull → edit → push workflow

# Download flow YAML from the server
fyrn pull my-flow

# Edit locally in your IDE
# The file is at ./flows/my-flow.yaml

# Review your changes
fyrn diff my-flow

# Upload as draft
fyrn push my-flow

# Deploy the updated version
fyrn flow deploy <flow-id>

Edit via MCP

AI agents can edit flows through the edit_flow tool (tier 3):

{
  "name": "edit_flow",
  "arguments": {
    "flow_id": "...",
    "yaml_config": "flow: updated-flow\nversion: 2\n...",
    "change_summary": "Added dedup config to prevent duplicate processing"
  }
}

---

Flow validation

Every flow goes through a four-stage validation pipeline before it can be deployed:

1. YAML parse — The file is parsed as YAML. Syntax errors (bad indentation, unclosed quotes) are caught here.
2. Schema validation — The parsed structure is validated against the fyrn DSL JSON Schema. This catches missing required fields, invalid field types, and unknown properties.
3. Expression parsing — All mapping expressions (e.g., source.total_price | decimal(2)) and when: conditions are parsed. Invalid function names, malformed pipes, and unresolved references are flagged.
4. Compilation — The flow is compiled into the runtime execution plan. This catches cross-cutting issues like circular store_as references or incompatible step configurations.

Run validation locally before deploying:

fyrn flow test flows/my-flow.yaml --sample-data test.json

Common errors

Error	Cause	Fix
Missing source	Flow has no source config	Add source: block
No target/steps/fan_out	Flow has no output	Add target:, steps:, or fan_out:
Unknown transform	Typo in transform name	Check Transforms Guide
Invalid condition	Malformed when: expression	Check condition syntax
Max nesting depth	Array maps nested > 5 levels	Flatten your mapping

---

What’s next

• Transforms Guide — All transform functions
• DSL Reference — Full YAML specification
• Testing Flows — Test before you deploy