Borgiq Builder

BorgIQ Builder

Build Actors and Triggers that power BorgIQ automation workflows.

Table of Contents

• BorgIQ Platform Overview
• Routing to Specialized Skills
• TypeScript Definitions
• Task Actor Types
• Trigger Actor Types
• Common Actor Structure
• Actor Naming Conventions
• Configuration Interpolation Order
• BorgIQ Expressions
• Context Variables
• Q-lib Functions
• Actor Source Files
• Actor Memory
• Authentication
• Actor ID, Validation, and Post-Processing
• Generation Instructions
• Workflow Composition
• Actor Connections and Edges
• Workflow Examples
• Workflow Patterns
  • Web apps and forms — handed off to spokes
  • Collection migrations and provisioning
  • Streams: events in order, consumed by cursor
• Editing Existing Workflows
• Migration from Other Platforms
• Deploying and Testing with the CLI
  • Canvas Bundles
  • CLI Command Reference
  • CLI Data Formats
  • CLI Scaffolding Scripts
  • CLI Troubleshooting

BorgIQ Platform Overview

BorgIQ is an automation platform where nodes are called Actors. Workflows chain Actors together with connections (edges). Each actor emits messages stored under msg.ActorName.

Workspaces and Canvases

BorgIQ organizes workflows in a hierarchical structure:

Slug Format:

• Workspace slugs: 5-10 lowercase alphanumeric characters with hyphens (e.g., john-dev)
• Canvas slugs: 2-255 lowercase alphanumeric characters with hyphens (e.g., skill-test)

Cross-Canvas/Workspace Calls: Actors can invoke sub-flows in other canvases or workspaces using CallFlowActor. When workspaceSlug or canvasSlug is omitted, the current workspace/canvas is assumed.

Actor Categories

There are two categories of actors:

Example workflow: TriggerActor -> TaskActor1 -> TaskActor2 produces:

{
  "msg": {
    "trigger_actor": { "...output from trigger..." },
    "task_actor_1": { "...output from task 1..." },
    "task_actor_2": { "...output from task 2..." }
  }
}

Concurrent Execution Model

BorgIQ executes all downstream actors concurrently by default. When an actor emits a message, all connected downstream actors start executing in parallel without any explicit configuration.

     A
    / \
   B   C      <- B and C run concurrently when A emits
    \ /
     D        <- D receives TWO separate messages (one from B, one from C)

Key behavior:

• If A connects to both B and C, both B and C execute concurrently when A emits
• D will receive two separate messages and execute twice (once for B's output, once for C's output)
• No fork action is needed for parallel execution—it happens automatically

When to use fork/forkJoin:

Only use the fork and forkJoin MessageProcessorActor actions when you need to synchronize parallel paths and emit a single combined message. See message-processor-actor.md for detailed documentation, workflow-patterns.md for complete examples, and fork-join-common-mistakes.md for common pitfalls to avoid.

Critical rules:

• forkJoin requires enableSTM: true
• MessageProcessorActor always uses only SPRTdefault (fork uses multiple edges, not multiple sourcePorts)
• Only RouterActor, AiRouterActor, InterfaceActor, AiAgentActor, and AgentHarnessActor use multiple sourcePorts

Routing to Specialized Skills

This skill is the hub of the borgiq-builder plugin. It covers actor wiring, edges, msgVars, expressions, and overall workflow composition. Four spoke skills ship in the same plugin and load automatically when their domain appears in the user's request. Pull them in actively when the work crosses into their area — they're more opinionated and focused than this hub.

Cross-domain example: "build a flow with an interface form that takes a customer name, hands it to an AI agent that researches them, posts the result to Slack" → hub orchestrates + borgiq-form-builder designs the form + borgiq-agent-builder designs the agent + borgiq-json-schema-builder defines the research output schema. The hub stays in context throughout and handles wiring, edges, IDs, and the Slack HTTP actor.

TypeScript Definitions

Complete TypeScript/Zod schema definitions for all actors are available in references/typescript/. Use these to understand exact data structures, validation rules, and type constraints.

Usage: When building actors or understanding output structures, read the relevant TypeScript reference markdown file to find exact field names, types, and validation rules. Each file contains a table of contents linking to individual type definitions.

Task Actor Types

⚠️ Before hand-building an integration actor — especially an HttpRequestActor — search the template catalog first. BorgIQ ships vetted templates for most third-party actions (Gmail, Slack, GitHub, Google, Notion, …). Adapting a template is the single biggest defense against the most common failure mode: hand-writing an actor's options, sourcePorts, and schemas from scratch and getting them subtly wrong. Only hand-build when no template fits.

borgiq templates apps --search "<vendor>" --json     # run a few queries, e.g. gmail, google, slack
borgiq templates list --app-id TAPP... --json        # list that app's templates (paginates/sorts)
borgiq templates get ATMP... --json \                # fetch the chosen template, then convert it:
  | borgiq scaffold actor-from-template --output actor.json --print-id
borgiq canvas-actors create <canvasSlugOrId> <actorId> --file actor.json --json

In a bundle, write the templates get actor payload (already ExportedCanvasActor object shape) as actor.yaml, apply the template fixups (fresh actor ID and trigger keys, keep template provenance), and complete the three-edit rule. scaffold actor-from-template produces the YAML-string CanvasActor mutation shape for the direct/batch fallback and performs those fixups automatically. Full flow: Deploying and Testing with the CLI.

Choosing a Task Actor Type

Important: DenoActor vs MessageProcessorActor

Use MessageProcessorActor as the default for data transformations. It handles most transformation needs via YAML configuration and ${{ }} expressions without custom code.

Use DenoActor (or PythonActor) ONLY when you need:

• Fetch/HTTP requests - Making API calls within custom logic
• I/O operations - File handling, network calls, or async operations
• NPM/external libraries - Using third-party packages not available in Q-lib
• Complex imperative logic - Loops, recursion, or stateful algorithms that can't be expressed declaratively

Important: Prefer PythonActor when CLI tools are needed. If the workflow needs to run command line applications available on the Lambda image (e.g., git, aws-cli, jq, ImageMagick, tar), use PythonActor. DenoActor has no shell access. PythonActor can invoke these tools via subprocess.run().

If the task can be done with ${{ }} expressions and Q-lib functions, use MessageProcessorActor.

Important: Avoid overusing DenoActor for data transformation. Any actor's vars and outputs configuration sections support ${{ }} expressions. Use vars for intermediate computations and outputs for formatting the final result. Only reach for DenoActor when you need fetch, I/O, or imperative logic.

Trigger Actor Types

Trigger actors start workflows (flowruns). Each workflow must have exactly one trigger, but a canvas can contain multiple workflows, each with its own trigger.

Choosing a Trigger Type

Universal Trigger vs Webhook Trigger (HTTP endpoints)

Both build HTTP endpoints, but they sit at opposite ends of a spectrum: a UniversalTriggerActor is the whole handler (request parsing, auth, storage, validation, and response all run inside its receive code), while a WebhookTriggerActor is the entrance to a multi-actor flow that does the work downstream.

Rules of thumb:

• Self-contained CRUD / lookups → Universal. If a route is "parse the request, read/write a Collection, return JSON," keep it inside one UniversalTriggerActor and respond from its code. No edges, no downstream actors.
• Orchestration → Webhook. The moment a route needs an LLM call, a third-party API, conditional routing, or a fan-out/fork, use a WebhookTriggerActor feeding the real actors and a WebhookResponseActor (or AiActor → WebhookResponseActor) for the reply.
• Don't collapse endpoints into one Universal Trigger just to reduce actor count. If even one route needs downstream actor orchestration, give that route its own WebhookTriggerActor rather than forcing AI/integration logic into trigger code. Mixed canvases (some Universal routes, some Webhook routes) are normal and correct.

URL wiring note: the two trigger types expose their URLs under different context maps — ${{ ctx.canvas.webhookTriggers.<msgVar>.url }} for a WebhookTriggerActor, ${{ ctx.canvas.universalTriggers.<msgVar>.url }} for a UniversalTriggerActor (which appears there only when configuration.webhook.enabled: true). The URL shape is identical; only the map differs.

See universal-trigger-actor.md and webhook-trigger-actor.md for full configuration. For app frontends calling these endpoints, the borgiq-react-app-builder spoke owns the wiring (see Web apps and forms — handed off to spokes).

Trigger Output

All triggers emit a message accessible to downstream actors via msg.<trigger_msgVar>. The message structure varies by trigger type—see the TypeScript schemas in references/typescript/actor-schemas-triggers.md for exact definitions:

• ButtonTriggerActor: Emits the configured options payload
• WebhookTriggerActor: Emits { meta, method, headers, body, queryParams, rawBody?, response? }
• EmailTriggerActor: Emits { messageId, from, to, subject, date, hasAttachments, textBody, htmlBody, attachments, headers }
• InterfaceTriggerActor: Emits { meta: { submissionInterfaceId, user }, body: { ...field values... } }
• AppTriggerActor: Does not emit messages (no downstream workflow). Hosts a web application only.
• ScheduledTriggerActor: Emits { triggeredAt, lastTriggeredAt }
• UniversalTriggerActor: Emits whatever results the user code returns (free-form; results: undefined emits nothing)
• CallableTriggerActor: Emits the payload passed by the parent flow

Important: When a task requires multiple HTTP requests stitched together, use a DenoActor or PythonActor instead of chaining multiple HttpRequestActors. See multi-api-examples.md for TypeScript and Python examples.

Common Actor Structure

All actors share a common YAML structure.

Important: Do not confuse actor-level schemas with actor-specific schema options.

• actors.ACTRxxxxx.schemas.inputs and actors.ACTRxxxxx.schemas.outputs define the actor's reusable interface—what inputs the actor accepts and what outputs it produces. These are used for templatization and validation at the actor boundary.

• actors.ACTRxxxxx.configuration.options.inputSchema or outputSchema are actor-specific configuration options with different purposes. For example, AiActor's configuration.options.outputSchema tells the AI model to produce structured output matching that schema—it's a directive to the LLM, not a definition of the actor's interface.

metadata:
  schemaVersion: v1.0
  source: BIQCanvas
actors:
  ACTR01xxxxx:
    type: HttpRequestActor  # or DenoActor, AiActor
    version: 1
    name: Actor Name Here
    msgVar: actor_name_here
    description: What this actor does
    isActive: true
    continueOnError: false
    enableLTM: false
    enableSTM: false
    sourcePorts:
      - id: SPRTdefault
    configuration:
      inputs:
        # Map upstream data and parameters here, e.g.
        userId: ${{ msg.fetch_user.id }}
        limit: 50
      # vars: (optional — only if you need to reuse a derived value within this actor)
      #   - intermediateName: ${{ Q.lo.camelCase(inputs.userId) }}
      options:
        # Actor-type-specific options — reference ${{ inputs.* }} (or ${{ vars.* }} if defined)
      outputs: ${{ results.body }}
      connection:
        key: connection-key-from-workspace
      error:
        if: ${{ error_condition }}
        retryIf: ${{ retry_condition }}
        message: ${{ error_message }}
    schemas:
      inputs:
        type: object
        properties:
          fieldName:
            type: string
            title: Field Title
            description: Field description
        required:
          - fieldName
    id: ACTR01xxxxx
    position:
      x: 0
      'y': 0
    edges: {}

Actor Naming Conventions

Use concise, descriptive names with proper noun capitalization.

Good names:

• Fetch user profile from Gmail
• Create Issue in GitHub
• Process calendar events
• Transform data for Airtable

Bad names:

• Gmail: Fetch user profile (wrong format)
• Create Issue (missing context)
• Find users (too vague)

Configuration Interpolation Order

BorgIQ actors are designed to be templatized and reusable. Configuration sections are processed in order:

1. inputs — The actor's parameter surface. Map all upstream actor data here using ${{ msg.<upstream_msgVar>.field }}, ${{ ctx.* }}, or ${{ err.* }}. Every parameter the actor consumes should pass through inputs and be declared in schemas.inputs. Inputs are interpolated first.

2. vars — Optional. Intermediate values reused within this actor's own options/outputs. Only add vars when the same derived value is referenced from more than one place inside the actor (e.g. building an email body that's then base64-encoded and referenced from options). Can reference inputs. If the value is used once, inline it instead — vars is not a wiring layer.

3. options — Actor-specific configuration. Has access to inputs, vars, msg, ctx, and err.

4. Actor executes — Results are stored in results.

5. error — Error handling. Has access to results. Determines if the actor failed and whether to retry.

6. outputs — Output transformation. Only evaluated if no error. Transforms results for downstream actors.

inputs vs vars — the rule

Inputs are the wire. vars is local scratch space. Mapping upstream msg.* data into vars is wrong even though both can hold any expression: it leaves the actor's declared input schema empty, breaks reusability, and forces options/prompt/body to reference vars.X instead of the actor's real parameter surface.

Anti-pattern (do not generate this):

configuration:
  vars:
    - name: ${{ msg.normalize_lead.name }}        # WRONG — upstream data belongs in inputs
    - company: ${{ msg.normalize_lead.company }}
  inputs:
    name: ''                                       # WRONG — declared inputs left empty
    company: ''
  options:
    prompt: 'Research ${{ vars.name }} at ${{ vars.company }}'  # WRONG — should reference inputs

Correct:

configuration:
  inputs:
    name: ${{ msg.normalize_lead.name }}
    company: ${{ msg.normalize_lead.company }}
  options:
    prompt: 'Research ${{ inputs.name }} at ${{ inputs.company }}'
# No vars needed — single-use values stay inline.

Correct use of vars (intermediate reused inside the actor):

configuration:
  inputs:
    from: ${{ msg.trigger.from }}
    to: ${{ msg.trigger.to }}
    body: ${{ msg.trigger.body }}
  vars:
    - rawEmail:
        - 'From: ${{ inputs.from }}'
        - 'To: ${{ inputs.to }}'
        - ''
        - ${{ inputs.body }}
    - encoded: ${{ Q.toBase64(vars.rawEmail.join('\r\n')) }}
  options:
    body:
      raw: ${{ vars.encoded }}     # vars.encoded is reused; building it inline would duplicate logic

BorgIQ Expressions

Use ${{ <javascript-expression> }} for Deno-compatible JavaScript expressions. Only YAML values can contain expressions.

Available: Q.* utility functions (see q-lib.md), all JavaScript web standard globals (btoa, JSON.parse, Math.*, array/string methods, etc.)

Restrictions: NO I/O operations (fetch, file system). Pure computation only.

Examples:

url: https://api.example.com/users/${{ inputs.userId }}
body: ${{ Q.toJSON(inputs.data) }}
data: ${{ msg.previous_actor.body }}

Context Variables

See references/context.md for full documentation.

For error handling patterns (continueOnError, split/collect, fork/forkJoin), see error-handling.md.

Q-lib Functions

Access utility functions via Q.*. See references/q-lib.md for complete reference.

Common functions: Q.toJSON(), Q.toBase64(), Q.isHTTPStatusInRange(), Q.lo.* (Lodash), Q.dateFns.* (date-fns)

Actor Source Files

Code-running actors — DenoActor, DenoTestActor, UniversalTriggerActor, PythonActor — carry their source in configuration.codeDir: a list of {path, content} files forming a small project, a sibling of options and never interpolated.

configuration:
  options: {}
  codeDir:
    - path: main.ts          # required entrypoint (main.py for PythonActor)
      content: |
        import type { Request, Response } from "@borgiq/actors";

        import { format } from "./lib/format.ts";

        export default async function receive(req: Request): Promise<Response> {
          return { results: format(req.inputs) };
        }
    - path: lib/format.ts
      content: |
        export const format = (inputs: unknown) => ({ inputs });

• Exactly one entry must be the entrypoint: main.ts for the three Deno-family types, main.py for PythonActor. Everything else is yours to arrange in folders.
• Import your own files relatively — ./lib/format.ts in Deno (extension included), from lib.format import format in Python (packages need __init__.py). Imports may not leave the actor's own files.
• ${{ }} inside source is literal text, never an expression: pass runtime values through configuration.inputs and read req.inputs.
• Some filenames are reserved by the runtime, and the tree is capped at 200 files / 1 MiB. Per-type details: deno-actor.md → Code Files, python-actor.md → Code Files, universal-trigger-actor.md → Code Files. In a canvas bundle the same tree is real files under the actor's code/ directory (canvas-bundles.md).
• Imports may not leave the actor's own files, and this is enforced. A relative import that escapes the actor's tree fails when the actor loads — the error tells the user that the actor imports something outside its own code directory, and (on a deployed workspace) the build names the specifier. Use relative imports between your own files, @borgiq/actors, npm:/jsr:/node: packages, or an approved https: host.
• Pin npm: and jsr: versions exactly — npm:escape-html@1.0.3, never bare or a ^ range. On a deployed workspace a build resolves each specifier once and every run uses that resolution, so an unpinned specifier makes what you get depend on when the canvas was last built.
• Actors written before multi-file support carry a single configuration.code string instead. They keep running and convert on the next save; write codeDir for anything new, and never set both fields.

(ReactAppTriggerActor also uses configuration.codeDir, for a whole Vite project — see the borgiq-react-app-builder spoke. AppTriggerActor keeps configuration.options.html / .css / .script.)

On a deployed workspace, a canvas's code actors are compiled ahead of time and every run — triggers and editor test runs alike — executes that build rather than the canvas's current code, so an edit takes effect only after the next build; a canvas with no fully successful build cannot run at all. See references/deployment.md.

Actor Memory

Code-running actors (DenoActor, PythonActor, UniversalTriggerActor) carry two key-value memory stores, STM and LTM. Every actor has both, alwa

…(truncated)