Skip to content

Working with Connections

Connections define reusable endpoints and credential configurations for your workflows. They represent physical or logical integrations (like an API, SFTP server, or Message Broker).

Type-First Management

Within MeshFlows, connections are managed primarily by their Type. The type determines which configuration properties are available and how the platform handles authentication.

Common types include: - http: REST/Web APIs with optional OAuth 2.0. - ssh: Remote execution via SSH. - sftp: File transfers over SSH. - ftp: Legacy FTP/FTPS transfers. - rabbitmq: AMQP 0.9.1 message exchange. - positionstack: Positionstack geocoding (capability provider). - weatherstack: Weatherstack weather data (capability provider).

Registry-driven providers (positionstack, weatherstack) need no orchestrator env changes — deploy the egress service and reference connections in workflow service_call steps. See Deploy integration contract.

Connection Lifecycle

Connections can be defined in two ways: 1. Repository-based: Defined in flows/connections/*.yaml. These are versioned and deployed with your code. 2. Dashboard/Runtime-managed: Overridden or created directly via the Connections panel in the Dashboard.

Note: Changes made in the Dashboard are stored in the Runtime Store and take precedence over repository files for immediate lifecycle management.

Examples

HTTP with OAuth 2.0 (Client Credentials)

The http type supports automatic OAuth 2.0 bearer token caching and refresh.

name: salesforce_api
type: http
base_url: https://your-instance.salesforce.com
oauth:
  token_url: https://login.salesforce.com/services/oauth2/token
  client_id: "$secret:sf-client-id"
  client_secret: "$secret:sf-client-secret"
  scope: "api"

SFTP with Private Key

name: crm_export_ftp
type: sftp
host: sftp.example.com
port: 22
username: "svc_meshflows"
private_key_pem: "$secret:transfer-ssh-key"

IMAP with Gmail

Use an App Password, not the normal Google account password.

name: google_mailbox
type: imap
host: imap.gmail.com
port: 993
username: your-account@gmail.com
password: "$secret:google-imap-app-password"
use_ssl: true

Gmail checklist: - Enable IMAP in Gmail settings for the mailbox. - Enable Google 2-Step Verification. - Generate an App Password and store it as a runtime secret. - Reference that secret in the connection using $secret:<name>.

Dashboard Management

The Dashboard provides a structured view of all active connections: - Grouped by Type: Connections are organized by their protocol (HTTP, SFTP, etc.) for better overview. - YAML Editing: You can perform "small edits" (like updating a base_url or port) directly by clicking a connection and choosing Edit YAML. - Secret Masking: While you can point to secrets using $secret:name, the dashboard will never expose the underlying sensitive values.

  • Metadata in Git: Keep non-sensitive connection metadata in your repository.
  • Secrets in Stores: Reference secrets by name; do not commit actual values.
  • Logical Names: Use descriptive names like inventory_service rather than api_server_01.