## Overview

Building the flow on the canvas is only the start. Then comes **operation**: taking the flow live,
keeping a version history so you can roll back safely, watching **sessions** (each run of the flow in a
conversation), reading performance **reports**, **organizing** flows into folders, and **connecting
external data** to the SQL node. The **Mass runs** tab completes the operation: run a published
flow against an entire audience (mass run) with anti-ban pacing — see the dedicated article under
**See also**.

This article covers the lifecycle of a flow on Conversa Labs after it has been designed. To learn how to
build the flow itself, see the Flow Builder article under **See also**.

## Prerequisites

- The **Flow Builder** module enabled for your account.
- **Administrator** to publish/unpublish, version, manage folders and manage database connections.
  **Agents** can list and monitor sessions, open reports and use connections that already exist.
- For the **SQL** node (`sql_query`): an external database connection configured and tested.
- For reports and monitoring to be meaningful: at least one published flow in use.

## Step by step

1. **Publish** the flow when it is ready. From then on its triggers can start it.
2. Monitor **sessions** in the run list: filter by flow, conversation or status.
3. Open the **reports** to see volume, completions and failures over a period.
4. When you need a change, edit the **draft** and publish again — the previous version stays in history
   so you can **roll back** if needed.
5. **Organize** flows into folders by team or purpose.
6. If a flow reads data, create and **test** the database connection before using the SQL node.

## Settings & options

### Publishing and versions

- **Publish / Unpublish**: publishing makes the flow live for its triggers; unpublishing takes it
  offline without deleting it.
- **Draft**: the editing copy. Saving the draft validates the definition and **never** touches the
  published version — you can edit freely without affecting flows already running.
- **Version history**: each publication stores a version. You can **open** an old version to review what
  changed.
- **Restore (roll back)**: brings a previous version back as the current one.
- **Duplicate**: creates a copy of the flow so you can experiment without risk to the original.
- **Purge (permanent delete)**: removes the flow permanently. This action cannot be undone.

### Session monitoring

A **session** is one run of the flow inside a conversation. From the list you can:

| Action | What it does |
| --- | --- |
| List / filter | View sessions by **flow**, **conversation** or **status** (running, waiting, completed, failed, canceled), paginated. |
| Cancel | Stops an **active** session (running or waiting) and releases the conversation. |
| Rerun | Runs the flow **from the start** as a fresh session (same flow, conversation, contact and variables). Ideal for a session that failed or was canceled. |
| Resume | Forces a session **stuck in "waiting"** to continue from the current node, as if the wait had been satisfied. |
| Delete | Removes the session and its step trace. If it was active, the conversation is released first. |
| Bulk actions | Select several sessions and **cancel** (active ones only) or **delete** at once. |

### Runtime v2 metrics and alerts

The protected `/monitoring/metrics` endpoint publishes global and per-tenant metrics for trigger,
queue, resume, and due lag; step, effect, and provider latency; retries, deduplication, stale leases,
unknown effects, DLQ, locks, pools, and batches. It only exists after the operator configures
`OPERATIONS_METRICS_TOKEN`. Alerts are evaluated every minute and thresholds can be tuned with
`FLOW_BUILDER_ALERT_*` variables; episodes live in one TTL-bound Redis hash. No payload, secret,
contact, conversation, or personal data is published. Operators must apply the additive observability
indexes before enabling this collection at scale.

### Reports

Reports show the **execution metrics** of your flows — session volume, completions and failures. You can
filter by **flow** and by **period** (start and end date) to compare performance over time.

### Organizing into folders

Group flows into **folders** by team, channel or purpose. Deleting a folder **does not delete the
flows** inside it — they simply go back to having no folder.

### Database connections (SQL node)

The **SQL** node queries an external database using a **connection** you register once:

- **Create/edit a connection**: provide the adapter (PostgreSQL, MySQL or SQL Server), host, port,
  database, username and password. The **password is write-only** — it is accepted when you save but
  never returned to the screen. When editing, leave the password blank to keep the current one.
- **Test connection**: opens the pool and runs `SELECT 1` to confirm the credentials work.
- **Test query**: runs the node's query against a **bounded sample** and shows the rows **plus** the
  compiled SQL and parameters — you see exactly "what will run", with `{{ variables }}` resolved just
  like at runtime.
- **SQL template gallery**: ready-made read-only snippets (search, listing, aggregation, and joins) in
  the dialect of the chosen adapter, to fill the query field without starting from scratch.

The v2 runtime accepts one parameterized read statement per node. SQL writes are not shown in the
gallery and cannot be published until an administrator-only, human-confirmed surface exists.

### Write-only credentials for HTTP and webhooks

After an administrator provisions a vault credential, select it by name in the node. The flow
definition stores only an opaque reference:

- **HTTP request** supports bearer tokens, API keys, Basic Auth, and OAuth2. OAuth2 can use a static
  access token, `client_credentials`, or `refresh_token`; token exchange uses the same request limits
  and SSRF protection as the main request.
- **Outbound webhook** uses a separate signing credential.
- Secrets never enter the definition, export, history, or trace. Rotating a credential preserves the
  flow reference and invalidates the cached OAuth2 token.

### Import / export

- **Export**: downloads a flow's definition to store it or move it to another account.
- **Import**: creates a flow from an exported definition.
- **Test HTTP request**: fires a single request in isolation (without running the whole flow) to check
  the URL, headers and response before using it in a node.

## Use cases

- **Change a live flow safely**: edit the draft, publish, and if something goes wrong, **restore** the
  previous version in seconds.
- **Recover problem runs**: find failed sessions with the status filter and **rerun** them in bulk.
- **Unblock a stalled chat**: a "waiting" session that never received its reply can be **resumed**
  manually.
- **Look up orders inside the flow**: configure a database connection, validate it with "Test query" and
  use the SQL node to answer the customer with real data.

## Tips, limits & best practices

- Publish important changes during quieter hours and keep the history so you can roll back.
- **Rerun** creates a fresh session; it can be blocked if the flow is no longer published or if another
  active session already exists for the same conversation and flow.
- Bulk actions have a per-call item cap — for large volumes, repeat in batches.
- Treat the **database password** as a secret: it is write-only and never shown back in the interface.
- Always run **Test connection** and **Test query** before publishing a flow that uses the SQL node.

## Troubleshooting

- **Session stuck in "waiting"**: use **Resume** to force it to continue from the current node. This
  only works for sessions in that state.
- **Session failed or was canceled**: use **Rerun** to run the flow from the start as a fresh session.
  If it is blocked, confirm the flow is still published and that no other active session exists for the
  same conversation.
- **The database connection failed the test**: check adapter, host, port, database, username and
  password; verify the adapter is available on the server and that the network allows access.
- **Flow is published but never fires**: check the trigger and whether the flow is linked to the right
  inbox; look for errors in recent sessions and confirm the published version is the one you expect.

## See also

- [Flow Builder: build conversational flows visually](/hc/ajuda/articles/automation-flows-flow-builder-en)
- [Automation rules: triggers, conditions and actions](/hc/ajuda/articles/automation-flows-regras-de-automacao-en)
- [Automation and Flows overview](/hc/ajuda/articles/automation-flows-overview-en)
- [Mass runs in the Flow Builder](/hc/ajuda/articles/automation-flows-flow-builder-disparos-em-massa-en)