Flow Builder in production: sessions, versions, reports and database connections

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:

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
• Automation rules: triggers, conditions and actions
• Automation and Flows overview
• Mass runs in the Flow Builder