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 that bridges an external system to the Priostack execution engine. Connectors are composed of one or more activity blocks that run in sequence, transforming data as it moves from a source to a destination.

Every connector has a direction:

• Inbound — listens for events coming into Priostack from the outside world. An inbound connector exposes a webhook endpoint or a cron schedule. When triggered it can start a BPMN process instance, publish a message to a Layer 2 named channel, or simply log the event. Typical use-cases: receive Stripe payment events, accept GitHub webhook pushes, trigger a workflow from a scheduled job.
• Outbound — fires when a BPMN process reaches a service task whose topic matches the connector's configured topic. The connector carries the job payload through its activity chain and delivers a result (HTTP call, Telegram notification, email, etc.) before completing the job. Typical use-cases: call a third-party REST API, send a Slack message, push data to a warehouse.

Together, inbound and outbound connectors form a two-way bridge between BPMN processes and any REST-accessible external system — with no custom code required.

2. Base Activity Types

Each connector is a chain of activities. The table below lists all available activity types, their category, and what they do.

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.

Asynchronous

When enabled, the activity runs in the background and the connector continues to the next activity immediately without waiting for the result. Use this for fire-and-forget notifications or non-blocking I/O calls where the response is not needed downstream.

Repetitive

The activity repeats in a loop until a FEEL condition (specified in constraints) evaluates to true. Combine with a delay activity to implement polling.

Compensation

Marks the activity as a compensation handler. If a preceding activity fails, the compensation handler is invoked to roll back its side effects (e.g., delete a record created by an earlier HTTP POST). Mirrors BPMN 2.0 compensation events.

Escalation

On error, escalate to the parent scope instead of failing the connector. Useful inside sub-chains (conditional or retry blocks) where you want the outer connector to handle the failure.

Goto

Jump to a specific activity by its id field rather than proceeding sequentially. Set the goto field to the target activity ID. Useful for implementing simple loops without nesting a repetitive block.

Timer

Delay execution of this activity by an ISO 8601 duration before it runs (e.g., PT30S for 30 seconds, PT5M for 5 minutes). Unlike the Delay activity type, the Timer toggle applies to any activity type.

Constraints

A FEEL expression evaluated as a pre-condition before the activity runs. If the expression evaluates to false, the activity is skipped. Use constraints to guard activities on payload shape or business rules (e.g., payload.amount > 0).

Retry

Configure a maximum retry count (retry_max) and backoff strategy (retry_backoff: linear or exponential). The activity is re-attempted automatically on transient errors (HTTP 5xx, network timeout) up to the limit. Execution is aborted and the error is logged once the limit is exceeded.

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.

{
  "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": {},
      "constraints": "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