Documentation by ClonePartner

Start typing to search.

Using Envoy

Connectors and connected accounts

View Markdown

Create, test, edit, and delete Connectors from the UI, and connect provider accounts for catalog connector types.

Connectors and connected accounts

A Connector is a named, stored connection configuration — a database, a file directory, an object store, or a SaaS API. Tasks and Job Templates only declare typed connector slots; the Connectors screen is where operators create the real configurations that fill those slots. Creating, editing, testing, and deleting Connectors requires an admin or superadmin role.

Screen overview

Open Connectors from the sidebar. The page header shows a refresh button and, for admins, an Add Connector button. Below it, a toolbar provides a Search connectors... input and a Type filter (All Types by default).

The list shows one row per Connector with these columns:

  • Name — the Connector name with its type icon. Sortable.
  • Type — the connector type label.
  • Status — Configured for built-in types. Catalog connector types instead show Connected when a provider account is bound, or Not connected when it is not.
  • Description — the optional description, or a dash.
  • Created — the creation date. Sortable.

Each row ends with an edit (pencil) button and a row menu containing Test connection, Connect account or Reconnect account (catalog types only), Edit, and Delete. Long lists page with a load-more control at the bottom.

To create a connector

  1. Select Add Connector. The New Connector dialog opens with the prompt "Select a type and fill in the configuration."
  2. Enter a Name (for example production-db) and pick a Type. The type dropdown has a Search types… field; built-in types are listed before catalog types.
  3. Optionally add a Description.
  4. Fill in the Configuration fields. The form is generated from the connector type's schema: required fields are marked, secret fields render as password inputs with a secret badge and a reveal toggle, and repeatable groups have an Add button per item. A toolbar toggle switches between the form and a raw JSON editor (Switch to raw JSON / Switch to form view).
  5. Select Save. Saving first runs the connection test; the Connector is stored only when the test passes.

For per-type configuration keys, see the connector reference.

Secret fields and Azure Key Vault

Secret values are stored through the server's secret provider and are never returned in plaintext — when you edit a Connector, secret fields show Leave empty to keep current value. Leaving a secret blank keeps the stored value; entering a new value replaces it.

When Azure Key Vault is configured on the server, each secret field also shows a Select from Azure Key Vault button. It switches the field to a vault secret picker that stores a reference to the vault secret by name instead of the value itself; Enter value manually switches back.

To test a connection

  • In the dialog, select Test connection. The Connection Test panel lists each check the connector performs, with a Re-test link to run it again.
  • From the list, open the row menu and select Test connection to test a saved Connector without opening the editor.

Tests time out after 30 seconds. If the test fails, the dialog offers Save anyway so you can store a configuration whose target is temporarily unreachable.

Connected accounts for catalog connectors

Catalog connector types (SaaS integrations registered from the deployment catalog) do not use a configuration form. Instead, the dialog shows a Connected account panel:

  1. Enter a name and select Connect account. Envoy saves the Connector, then opens the provider's authorization page in a new tab.
  2. While you finish in the other tab, the dialog shows "Waiting for you to finish connecting in the other tab…" with Open connect page and Copy link actions. The link is valid for 24 hours and can be shared with another admin of the Envoy instance who has the account credentials.
  3. Complete the provider authorization. The callback page confirms Account connected, saves the account on the Connector, and returns to Connectors. From there you can select Continue or Open Explorer to query the new account directly.
  4. Back in the dialog, the panel updates automatically to show the connected account ID, and the list row's status changes to Connected.

To re-authenticate an existing account, use Reconnect in the dialog or Reconnect account in the row menu.

OAuth app credentials

Some catalog integrations require your own OAuth app before an account can be connected. When that is the case, the dialog shows an OAuth app section with the note "This integration needs your own OAuth app credentials before connecting." Enter the Client ID and Client secret and select Save OAuth app; the Connector must be saved first so the credentials have somewhere to attach. When editing later, leave the secret blank to keep the existing value.

To edit or delete a connector

  1. Select the pencil icon on a row (or Edit in the row menu) to open Edit Connector. The type of a catalog Connector cannot be changed after creation.
  2. To delete, select Delete in the row menu and confirm in the Delete Connector dialog. Deletion is permanent and cannot be undone — Jobs whose connector mapping references the deleted Connector will fail to resolve it, so rebind those Jobs first.

Where connectors are used

  • Jobs bind template connector slots to Connectors when a Job is created — see Connectors and slots.
  • Data Explorer queries any stored Connector interactively — see Data Explorer.
  • Standalone task runs bind a Connector per slot when you start a run from the Tasks screen.

File-capable connector types (CSV, YAML, S3, Azure Blob Storage) also accept file uploads, which surface as an upload action in Data Explorer.