Connectors

The manifest

Every integration is a directory under integrations/ containing an integration.yaml:

name: hubspot
slug: hubspot
description: HubSpot CRM integration
active: true
tags: [crm, sales]
category: [crm]
meta:
  vendor: HubSpot

Field	Required	Purpose
name	✅	The integration’s identity and the :name path segment
slug	✅	Prefix applied to every entity, job, and connector this integration ships (<slug>_…) so names never collide
active		Default true; false makes the dispatch routes return a not-active error
description, tags, category, meta		Catalog metadata, returned by GET /list

Connectors

A connector is the outbound call to the third-party API — a definition under bffs/. It declares a path and method (how it’s addressed through the service) and a list of endpoints[] (the actual upstream calls):

name: contacts
path: /crm/contacts
method: GET
endpoints:
  - name: fetch
    url: https://api.hubspot.com
    path: /crm/v3/objects/contacts
    method: GET
    headers:
      Authorization: "Bearer {{secrets.hubspot_token}}"
    expression:
      jq: '.results | map({ id, email: .properties.email })'

Field	Purpose
path, method	How the connector is reached: /<method> /integration/<name>/bff/<path>
endpoints[].url + endpoints[].path	The upstream base URL and path
endpoints[].method	Defaults to the connector’s method
endpoints[].headers	Headers sent upstream (author-controlled)
endpoints[].senduser	true forwards the caller’s platform token as Authorization: Bearer
endpoints[].body	A Liquid template rendered against query params + request body + prior endpoints’ responses, then sent as JSON
endpoints[].form[]	Multipart fields — each with a file, data, or Liquid template source
expression.jq	A jq program to transform the composed response
expression.code + expression.language	A script transform (js, js:v8, lua) instead of jq

Chaining

Each endpoint’s response is stored under its name and made available to later endpoints’ templates, so a connector can call endpoint A, then use A’s result to build endpoint B’s request — assembling a multi-call operation into a single connector.

Credentials

Third-party credentials are supplied in the connector definition — as header values (which can reference tenant secrets), or by forwarding the caller’s own token with senduser: true. Sensitive values should be tenant Vault references rather than literals.

Other bundle folders

Folder	Becomes
data/	Entity definitions, entity names prefixed with <slug>_
jobs/	Job definitions, name prefixed with <slug>_
workflow/	Workflow definitions, keyed by name
notification/templates/	Notification templates, keyed by name

A notification or workflow shipped by an integration is invoked through the dispatch routes (see API).