Configure integrations in the app DSL

Integration credentials are installation data, not source code. A manifest declares workflow behavior; users select or authorize the account connection separately.

Discover the live catalog

The target server is the source of truth for executable node identifiers and parameter schemas:

GET /api/v1/apps-layer/platform-schema
GET /api/v1/actions/catalog
GET /integrations/api/catalog

Use workflowNodes.nodes from the platform schema or data.actions from the action catalog. Integration-backed nodes include their provider grouping, required credentials, inputs, outputs, and configurable properties.

:::warning Do not guess node identifiers The enabled actions can differ by server and integration configuration. Copy the exact type or identifier reported by the target server. :::

Call an integration action

Use the generic node builder for any catalog action:

import {defineApp, nodes, resources} from '@twl-tool/app-sdk';

export default defineApp({
  key: 'crm-follow-up',
  name: 'CRM Follow-up',
  version: '1.0.0',
  permissions: ['workflows.execute'],
  resources: {
    workflowDefinitions: {
      createFollowUp: resources.workflow({
        title: 'Create follow-up task',
        desiredState: 'active',
        definition: {
          version: 1,
          default_runner: 'builtin',
          triggers: [{key: 'run', type: 'manual', launch: true}],
          steps: [
            nodes.call('create-task', '<catalog-node-identifier>', {
              connectionId: '{{ input.connectionId }}',
              title: '{{ input.title }}',
              dueDate: '{{ input.dueDate }}',
            }),
          ],
        },
      }),
    },
  },
});

The example parameter names are illustrative. Use the selected node's live properties and credentials definitions.

Connection rules

• Never place access tokens, client secrets, API keys, or refresh tokens in a manifest.
• Do not ship a user-specific connection ID as a default.
• Prefer an installation setting or workflow input for connection selection.
• Treat reconnect and revoked states as normal runtime conditions.
• Request only the app permissions needed by the surrounding workflow and surfaces.

Integration capability types

Type	Execution model	Best for
Authenticated request	Immediate provider API call	An endpoint that does not need a reusable catalog action
Action	On-demand typed function	Reads, writes, and multi-step provider operations
Sync	Scheduled or incremental ingestion	Indexes, reporting tables, and retrieval pipelines
Provider webhook	External service pushes an event	Near-real-time automation
Native trigger	TWL Tool emits or accepts an event	Manual, schedule, webhook, workflow, and browser automation

Provider actions and events are additive to the five native trigger modules. See Triggers for their exact DSL shapes and routes.

Validate against the target server

npx twl-tool validate twl-tool.app.ts --url https://twl-tool.example
npx twl-tool plan twl-tool.app.ts --url https://twl-tool.example --organization acme

Validation checks the manifest. Planning also resolves logical references and reports the account-scoped resources that a deployment would create or change.