Appearance
Overview reference
The Integrations branch of the Studio Explorer holds everything that connects the platform to other systems: the named connections that say where a system lives and how to sign in, the flows that move data, the triggers that start them, the queues and synchronizations that keep two sides in step, the connectors for messaging and payments, and the screens used to watch and repair what happened. The Overview screen is the entry point. It answers one question: is anything wrong with my integrations right now. It is read by administrators and integration owners.
This page also defines the platform model used by every other page in this folder. The older summary at Integration and Connector Designer lists what was added and when; the pages here describe each screen in full.
Overview
Where to find it
Studio Explorer > Workspace > Integrations > Overview. Page key integrations-overview.
What the screen shows
The screen makes four independent requests when it opens: flow monitoring, message monitoring, the connection list and the webhook overview. If one is refused (for example because the signed-in person lacks permission) the screen still renders the others and shows a warning, "Could not load flow runs, messages... You may not have permission to see them." The tiles for the missing source show a dash.
| Tile | Source | Meaning |
|---|---|---|
| Needs attention | Flow runs, messages, webhooks | Flow runs in status FAILED, plus DEAD, plus failed messages, plus webhook deliveries that failed for good in the last 24 hours. Red when above zero, green at zero. |
| Flows | Flow monitoring | Number of flows defined in the tenant. |
| Running or queued | Flow monitoring | Runs in status RUNNING plus QUEUED. |
| Dead letters | Flow monitoring | Runs in status DEAD. |
| Connections | Connection list | Number of named connections. |
| Flow failure rate | Flow monitoring | Percentage of completed runs (SUCCESS, FAILED, DEAD) that did not succeed. A dash until one run has completed. Amber above 5 percent. |
| Average run time | Flow monitoring | Mean duration in milliseconds of completed runs. |
| Messages today | Communications monitoring | Messages created today across all channels. |
| Messages pending | Communications monitoring | Messages not yet sent. Amber when above zero. |
| Messages failed | Communications monitoring | Messages in status FAILED. Red when above zero. |
| Webhooks failed (24h) | Webhook overview | Outbound deliveries that exhausted their attempts in the last 24 hours. |
Below the tiles six cards open other screens:
| Card | Opens |
|---|---|
| Integration Flows | Integration Flows |
| Email, SMS and WhatsApp | |
| Connections | Connections |
| Webhooks | Webhooks |
| External Connectors | External Connectors |
| LDAP / SSO | LDAP / SSO |
Actions
The screen has no write actions. Each card navigates. Back returns to the Studio home.
Permissions
Each tile calls an endpoint with its own check: integration.flow / view (flow monitoring and connections), communication / view (message monitoring), integration.webhook / view (webhooks). Without a permission the corresponding tile is empty and listed in the warning.
API and CLI
| Purpose | Request |
|---|---|
| Flow monitoring | GET /api/v1/integration/flows/monitoring |
| Message monitoring | GET /api/v1/communications/messages/monitoring |
| Connections | GET /api/v1/integration/connections |
| Webhook overview | GET /api/v1/integration/webhooks |
| One-call health summary | GET /api/v1/integration/health |
erp integration health prints the health summary: queues with dead messages, failing poll triggers and folder watches, syncs with open disagreements and the number of go-live requests waiting. The health response has healthy (true when no queue has dead messages, no active poll trigger has a last error and no sync has open disagreements), queuesWithDeadMessages, pollTriggersFailing, syncsWithOpenConflicts and goLiveRequestsPending. Folder-watch health is a separate call, GET /api/v1/integration/file-watches/health.
Platform model
Building blocks
| Block | What it is | Screen |
|---|---|---|
| Connection | A named record of an outside system: address, sign-in method and a stored secret. REST, SFTP, PostgreSQL database, GraphQL, SOAP and message-broker connections share one table, told apart by the connection type. | Connections |
| Flow | A stored sequence of steps (web calls, platform actions, mapping, conditions, waits) with a trigger. The unit of automation. | Integration Flows |
| Mapping and lookup table | Declarative rules that reshape one JSON document into another, and shared value tables those rules use. | Mappings, Lookup Tables |
| Event | A durable business fact (order.created) that flows and webhooks listen for. | Events |
| Trigger source | Something that produces events or runs without a person: a schedule, an inbound web address, a folder watch, a poll trigger, a queue. | Webhooks, Folder Watches, Poll Triggers, Queues |
| Synchronization | A saved comparison between a platform entity and an outside list, with a policy for disagreements. | Synchronization |
| Connector definition | A JSON description of one HTTP call to an outside provider, with a request template and a response mapping. Distinct from a connection. | Connector Catalog |
| Provider account | Credentials for a built-in Email, SMS, WhatsApp, payment, banking, government, calendar, LDAP or identity connector. | External Connectors |
| Published API | A key-protected address that lets an outside system run one flow or connector. | REST APIs |
Connection, connector and provider account
Three similar words name three different things.
| Term | Table | Used by |
|---|---|---|
| Connection | integration_connection | Flow steps (connectionCode), poll triggers, folder watches, queue bridges, synchronizations, GraphQL, SOAP and SFTP calls. |
| Connector definition | external_provider_definition, domain integration | Connector Catalog, integration.run, published APIs of kind connector. |
| Provider account | communication_provider_account, and the finance, calendar, LDAP and identity account tables | Email, SMS, WhatsApp, payments, banking, e-invoicing, calendar sync, directory sign-in. |
How the parts run together
- A trigger source produces an event, or a person or API starts a flow directly.
- Every flow whose trigger event matches (and whose optional filter passes) is queued as a run. A worker picks the run up, executes its steps in dependency order, and records it step by step.
- A step that calls an outside system uses a connection by code. The address and secret come from the connection, never from the flow.
- A run that fails after its retries ends FAILED or DEAD and appears in Failed Items, where it can be corrected and sent again.
- Every run, event, queue message and synchronization run of one business event shares a correlation id and can be followed on Trace an Event.
Tenant isolation
Every request carries the X-Tenant-Id header and every table is keyed by tenant. A flow, connection, queue or webhook with the same code in two tenants is two unrelated records. Event delivery, queue dispatch and the schedulers iterate tenants one at a time. Inbound web addresses (flow webhook receivers, published APIs, payment and messaging webhooks) take the tenant id as part of the call, so a caller can only reach the tenant it names, and each is still authenticated by secret, signature or key.
Secrets handling
- A secret is write-only. List and get calls return
hasSecretand never the value. A password typed into Studio is not shown again. - Connection secrets are stored encrypted (
enc:v<keyVersion>:...) when encryption on write is switched on for the server, off by default; values written before that stay readable. Webhook signing secrets and connector secrets are kept in the tenant secret store; a published API key is hashed and shown once at creation. - Credentials never travel in an export bundle. After an import the connection exists without its password and is reported as needing credentials.
- Run history masks values by field name (password, secret, token and similar) before they reach Studio, the API, or the AI failure analysis.
- Outbound addresses are checked: they must be https and must not resolve to a private, loopback, link-local or multicast address, unless the operator allows private endpoints. Redirects are not followed for webhooks and connector calls.
Idempotency
| Where | Mechanism |
|---|---|
| Starting a flow | The X-Idempotency-Key header on POST /api/v1/integration/flows/{code}/execute, on the flow webhook receiver, on published API calls and on POST /api/v1/integration/run. |
| Signed inbound flow webhooks | The sender's webhook-id becomes the key (webhook:<id>), so a retrying sender never starts the flow twice. |
| Publishing an event | The X-Idempotency-Key header or idempotencyKey field. A repeat returns the first event with duplicate true and status 200 instead of 202. |
| Queue messages | dedupeKey: the same key is stored once; the publish response then has duplicate true. |
| Outbound webhooks | Every delivery of one event carries the same body and event id; the receiver is expected to de-duplicate. |
| Poll triggers and folder watches | Each item or file is announced once (items already present at the first look are not announced). |
| Imports | Importing a bundle twice reports unchanged the second time. |
Permissions model
Integration endpoints check a resource and an action through the privileged-action gate: the actor must be Studio staff, Tenant Owner or Admin, or hold an explicit grant. A missing permission returns 403 with the message actor "<id>" lacks <resource>.<action> permission. The resources are:
| Resource | Actions in use |
|---|---|
integration.flow | view, create, publish, execute, cancel, retry, viewHistory, manage, delete, approve |
integration.definition | view, manage, approve, activate |
integration.template | view, install |
integration.connector | view, manage |
integration.mapping | view, manage |
integration.event | view, publish, replay |
integration.deadletter | view, replay, discard |
integration.webhook | view, manage |
integration.queue | view, manage, execute |
integration.sync | view, manage, execute |
integration.api | view, manage |
integration.bundle | view, manage |
integration.run | execute |
communication | view, manage, manage-providers, manage-templates, manage-routing, send, send.<channel> |
finance | view, manage, send |
integration | execute, view (GraphQL, SOAP and SFTP calls) |
Poll triggers, folder watches, go-live approvals, approvals, trace and health use integration.flow. See Permissions model.
Not available in this release
Certificate-based authentication in the connection dialog, tenant-published inbound REST beyond key-protected published APIs, and a generic inbound webhook receiver other than the per-flow receiver are not available in this release.
Related
Connections and Identity, Flows, Triggers and Synchronization, APIs, Connectors, Move between environments, Connect to another system, Send events with webhooks.