Home › Docs › Connector Builder

Connector Builder Documentation

Build integration routes using visual activity blocks

Last updated: 2026-04-07 · 15 min read · ← Back to Docs

1. What is a Connector?

A Connector is a named integration route meant to bridge an external system to the Priostack execution engine. A connector is composed of one or more activity blocks, stored in order, describing how data should move from a source to a destination.

Every connector has a direction:

• Inbound - declares events coming into Priostack from the outside world, with a webhook or a cron schedule as its trigger. A webhook connector gets the URL /api/connector/{id}/inbound; once published, that URL answers 501 and processes nothing. Intended use-cases: receive Stripe payment events, accept GitHub webhook pushes, trigger a workflow from a scheduled job.
• Outbound - declares the BPMN service-task topic it is meant to serve and the delivery it describes (HTTP call, Telegram notification, email, etc.). Nothing hands it jobs today. Intended use-cases: call a third-party REST API, send a Slack message, push data to a warehouse.

Until a connector runtime exists, build the same integrations with code you run: a worker that activates the service task's jobs (outbound), or your own endpoint that calls POST /api/v1/process-instances (inbound).

2. Base Activity Types

Each connector is a chain of activities. The table below lists the activity types the builder stores, their category, and what each block is meant to configure. None of them runs today.

3. Activity Control Flow

Every activity in a connector can have one or more control flow toggles enabled. These map directly to the toggles visible in the Connector Builder UI and are stored on the activity (async, repetitive, compensation, escalation, goto, timer, constraints, retry_max, retry_backoff). None of them is executed today; each description says what the toggle is meant to express.

Asynchronous

Marks the activity as fire-and-forget: the chain would continue without waiting for its result.

Repetitive

Marks the activity as meant to repeat, for example to poll together with a delay activity. It is a flag only: no loop condition is stored with it.

Compensation

Marks the activity as meant to undo the side effects of an earlier one (e.g., delete a record created by an earlier HTTP POST). It is unrelated to BPMN compensation, which the process engine does run (see BPMN Elements).

Escalation

Marks an error in the activity as meant for the parent scope (a conditional or retry block) rather than for the connector as a whole.

Goto

Names, in the goto field, the activity id the chain is meant to jump to instead of proceeding sequentially.

Timer

Stores an ISO 8601 duration (e.g., PT30S for 30 seconds, PT5M for 5 minutes) meant to delay the activity. Unlike the Delay activity type, the Timer toggle can be set on any activity type.

Constraints

A free-text condition stored with the activity. The Console builder sets it with a checkbox, as "true" or empty. Nothing evaluates it: it neither skips an activity nor filters a message. A filter's condition belongs in the filter activity's own config.

Retry

Stores a maximum retry count (retry_max, 0 = disabled) and a backoff strategy (retry_backoff: linear or exponential). They are not applied, because no activity runs.

4. Connector JSON Schema

The example below shows a complete connector definition as returned by GET /api/connectors/{id}/export. You can import this JSON on any account using POST /api/connectors/import, which creates a new draft connector (new id, version 1). config is free-form: the builder stores whatever a block's panel collects, and this example keeps the filter's condition in config.predicate. Export replaces config values whose key names a secret (secret, token, password, API key and similar) with ***redacted***.

{
  "id": "con_1712345678000000000",
  "name": "Stripe → Start Billing Process",
  "description": "Receive Stripe checkout.session.completed events and start a BPMN billing workflow",
  "type": "inbound",
  "trigger_type": "webhook",
  "webhook_url": "/api/connector/con_1712345678000000000/inbound",
  "status": "active",
  "version": 2,
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-07T08:30:00Z",
  "activities": [
    {
      "id": "a1",
      "type": "filter",
      "label": "Only completed checkouts",
      "config": {
        "predicate": "payload.type = \"checkout.session.completed\""
      }
    },
    {
      "id": "a2",
      "type": "transform",
      "label": "Extract customer data",
      "config": {
        "mapping": {
          "customerId": "payload.data.object.customer",
          "amount":     "payload.data.object.amount_total / 100",
          "currency":   "payload.data.object.currency"
        }
      }
    },
    {
      "id": "a3",
      "type": "http",
      "label": "Enrich from CRM",
      "config": {
        "method": "GET",
        "url": "https://crm.example.com/api/customers/{{output.customerId}}"
      },
      "retry_max": 3,
      "retry_backoff": "exponential"
    },
    {
      "id": "a4",
      "type": "output",
      "label": "Start billing process",
      "config": {
        "output_type": "process_start",
        "process_key": "billing_workflow",
        "variables": {
          "customerId": "output.customerId",
          "amount":     "output.amount",
          "crmData":    "output"
        }
      }
    }
  ]
}

5. Quick-start: First Connector Deployment

6. FAQ