# Building Workflows

The orchestration editor lets you design multi-step workflows visually.

## Triggers

Every orchestration starts with a trigger:

### Simple Time Trigger
Schedule the orchestration to run at a specific date and time. This is useful for one-time campaigns or scheduled outreach.

### Event-Based Trigger
Start the workflow when a specific event occurs:
- Contact created or updated
- Form submitted
- Tag added
- Deal stage changed

### Manual Trigger
Start the workflow on demand from the UI or API.

## Actions

Add actions as steps in your workflow:

### Send Email
Use an email strategy to send a personalized email to the contact. Select the strategy and configure any needed overrides.

### Make Voice Call
Trigger an outbound call using a voice campaign.

### Send SMS
Send a text message using an SMS agent.

### Task Agent
Run an AI task agent as a workflow step. The agent receives accumulated data from prior steps and can reference that data in its instructions using **placeholder syntax**:

```
{{ key_name }}
```

For example, if a Store Read step loaded `accounts_receivable`, or a prior task agent produced `taskAgentResponse`, you can write:

```
Here is the data to process:

{{ accounts_receivable }}

Previous analysis: {{ taskAgentResponse }}
```

When a task agent runs inside an orchestration, it also receives the **update_orchestration_store** tool automatically. This allows it to write structured results back to the orchestration store without requiring a separate Store Write step.

### For Each
Iterate over an array from a prior step and run nested actions for each item. Configure the source key, an item variable name, and an iteration mode:

- **Sequential** — one at a time, waits for each to finish
- **Batch** — queue all at once
- **Time-Delayed** — stagger with a configurable delay between items

Drag steps into the for-each body on the canvas to define what runs per item. See [Recurring Workflows](/help/orchestrations/recurring-workflows) for more detail.

### Store Read / Store Write / Store Clear
Use these actions to interact with the orchestration's persistent data store. See [Recurring Workflows](/help/orchestrations/recurring-workflows) for more detail.

### Wait
Pause the workflow for a specified duration before proceeding to the next step.

## Branching

Add conditional branches based on contact behavior or workflow context:

### Email Branch
Branch based on whether the recipient:
- **Opened** the email
- **Clicked** a link in the email
- Did **neither** within a time window

Example: send an email, wait two days, then branch based on whether the message was opened.

### Condition Branch
Branch based on contact properties, tags, or custom field values.

## Workflow Examples

### Follow-Up Sequence
1. Send introductory email
2. Wait 3 days
3. Branch: If email opened → Make follow-up call; If not → Resend email with new subject
4. Wait 2 days
5. Send SMS check-in

### Event-Driven Nurture
1. Trigger: Form submitted
2. Send welcome email
3. Wait 1 day
4. Make introductory call
5. Wait 7 days
6. Send follow-up email

## Building Orchestrations via MCP

In addition to the visual editor, orchestrations can be created and managed programmatically through Karmaflow.ai's built-in MCP server. This allows external AI agents (Claude Desktop, Cursor, Windsurf, or custom applications) to build workflows on your behalf.

The MCP server provides tools to:

- **List, get, create, update, and delete** orchestrations
- **Toggle** orchestrations on/off
- **Validate** step arrays before saving
- **Browse** the trigger catalog and reference data (agents, strategies, campaigns, lists)

Steps are provided as an ordered array of `{ type, name, config }` objects. The server auto-generates step IDs and links steps in sequence — no need to manage the graph manually.

### Step Configuration Quick Reference

#### Triggers (type: "trigger")

| Name | Key Config Fields |
|------|-------------------|
| Event trigger (name: `""`) | `triggerKey` — key from trigger catalog |
| `simple-time` | `datetime` (ISO 8601), `timezone` |
| `recurring-schedule` | `frequency`, `time`, `timezone`, `daysOfWeek`, `dayOfMonth` |
| `call-end` | `voiceCampaign` (ID), `scopeToPlaceCall` (bool) |
| `chat-session-end` | `chatAgentId` (ID) |
| `agent-form-submission` | `formId` (ID) |
| `form-endpoint-submission` | `formEndpointId` (ID) |

#### Actions (type: "action")

| Name | Key Config Fields |
|------|-------------------|
| `mail-agent` | `strategy` (ID), `includeLists` ([IDs]) |
| `sms-agent` | `smsAgent` (ID) |
| `voice-agent` | `voiceCampaign` (ID) |
| `task-agent` | `taskAgentId` (ID), `taskInstructions` |
| `wait` | `durationMinutes`, `durationHours`, `durationSeconds` |
| `push-to-zapier-webhook` | `webhookUrl` |
| `send-transcript-to-webhook` | `webhookUrl` |
| `store-read` | `keys` (array) |
| `store-write` | `keys` (array), `mode` ("merge" or "replace"), `values` |
| `store-clear` | `keys` (array) |
| `collect-via-email` | `to`, `subject`, `body`, `parseMode` ("ai", "csv", "raw") |
| `for-each` | `sourceKey`, `itemKey`, `iterationMode`, `delaySeconds`, `steps` |
| `local-list` | `rows` (array), `columns` (array), `fileName` |

#### Branches (type: "branch")

| Name | Key Config Fields |
|------|-------------------|
| `outcome-router` | `channel`, `sourceStepId`, `conditions: [{ triggerKey, label, steps }]` |
| `if-then-branch` | `conditions: [{ if, steps }]` |
| `ai-router` | `prompt`, `model`, `conditions: [{ id, label, description, steps }]` |

See [MCP Servers](/help/integrations/mcp-servers) for endpoint and authentication details.

## Orchestration Dashboard

Each orchestration includes a dashboard showing:

- Execution timeline
- Contacts at each step
- Branch distribution
- Completion and drop-off rates

<!-- SCREENSHOT: orchestration-editor.png — Orchestration workflow editor -->
<!-- SCREENSHOT: orchestration-dashboard.png — Orchestration execution dashboard -->