Service Bridge Steps in Activity Plans

A BRIDGE_CALL step calls a configured Service Bridge from an Activity Plan. It is the right tool when an external system call is part of the business process and should have its own status, result, logs, retry behavior, and audit trail. Service Bridges keep authentication, target URLs, request rules, caching, and endpoint configuration outside of the Activity Plan. The Activity Plan references the bridge and endpoint, then supplies the request data for this workflow.

When to Use a BRIDGE_CALL Step

Use a BRIDGE_CALL step when you need to:

Validate extracted data against a system of record
Fetch enrichment data before review
Post approved data to an ERP, loan origination, claims, KYC, or compliance system
Notify an external workflow when a Kodexa Activity completes
Keep the external call visible as its own monitored workflow step

Use serviceBridge.call() inside a SCRIPT step when the bridge call is only one part of a larger custom decision.

Step Configuration

{
  "slug": "post-approved-invoice",
  "type": "BRIDGE_CALL",
  "dependsOn": ["analyst-review:approved"],
  "serviceBridgeRef": "finance-erp",
  "endpointName": "post-invoice",
  "requestBody": {
    "documentFamilyId": "{{inputs.documentFamilyId}}",
    "sourceSystem": "{{inputs.sourceSystem}}"
  },
  "treatAsError": "$.status != 'accepted'",
  "timeoutSeconds": 30,
  "disableCache": true
}

Step field	Description
`serviceBridgeRef`	Service Bridge slug or ref
`endpointName`	Endpoint defined by the bridge
`requestBody`	Static body, template, or expression that builds the JSON request
`requestQuery`	Optional query-string template
`requestPath`	Optional path substitution
`requestHeaders`	Optional request headers, excluding secrets
`requestScript`	Optional JavaScript preprocessor for complex request construction
`bridgeActions`	Actions the bridge response can emit for downstream routing
`treatAsError`	Predicate that marks a response as a failed step
`timeoutSeconds`	Per-call timeout
`disableCache`	Whether to bypass bridge-level caching for this call

How It Runs

The step result is stored on the Activity step. Operators can inspect the response, failure details, and logs without digging through a script.

Request Mapping

Start with a static JSON body when possible:

{
  "requestBody": {
    "documentFamilyId": "{{inputs.documentFamilyId}}",
    "projectId": "{{project.id}}"
  }
}

Use requestScript when the request needs conditional shaping:

{
  "requestScript": "return { invoiceId: inputs.invoiceId, amount: Number(inputs.amount || 0), urgent: Number(inputs.amount || 0) > 10000 };"
}

Keep request scripts small. If you need several external calls or substantial document mutation, use a SCRIPT step.

Response Routing

A bridge call can emit actions so downstream steps depend on the external response.

{
  "slug": "validate-supplier",
  "type": "BRIDGE_CALL",
  "serviceBridgeRef": "finance-reference-data",
  "endpointName": "validate-supplier",
  "requestBody": {
    "supplierId": "{{inputs.supplierId}}"
  },
  "bridgeActions": [
    {
      "slug": "valid",
      "name": "valid",
      "when": "$.valid = true"
    },
    {
      "slug": "review",
      "name": "review",
      "when": "$.valid != true"
    }
  ]
}

Then route downstream work:

{
  "slug": "supplier-review",
  "type": "CREATE_TASK",
  "dependsOn": ["validate-supplier:review"],
  "taskTemplateRef": "supplier-exception-review"
}

Per-Document Bridge Calls

By default a BRIDGE_CALL step makes a single HTTP call for the whole Activity. Set perDocument to true to fan the step out into one call per routed document instead.

{
  "slug": "post-each-invoice",
  "kind": "BRIDGE_CALL",
  "config": {
    "serviceBridgeRef": "finance-erp",
    "endpointName": "post-invoice",
    "perDocument": true,
    "requestBody": {
      "sourceSystem": "{{inputs.sourceSystem}}"
    },
    "bridgeActions": [
      { "name": "posted", "when": "$.status = 'accepted'" },
      { "name": "review", "when": "$.status != 'accepted'" }
    ]
  }
}

When perDocument is enabled, the step processes the routed documents one at a time. Each call’s request context is augmented with that document’s documentFamilyId, extractedData (the document family metadata), and documentPath, so the same request mapping can reference the current document. Per-document behavior:

Each document resolves its own action. Response routing runs per call, so different documents can take different downstream branches.
Failures are isolated. A request-build error, a bridge transport error, or a treatAsError match fails only that document; the remaining documents continue. (An output-mapping expression that fails to compile or evaluate is logged as a warning and skipped — it does not fail the document.)
The step gets a consensus action only when every completed document resolves the same action. If documents disagree, no step-level action is emitted, but each document still records the action it resolved.
The join policy governs the step rollup. The default is ALL_SETTLED; set joinPolicy to ANY_BRANCH to complete the step as soon as one branch is satisfied.
Calls run sequentially. maxParallel does not apply to per-document BRIDGE_CALL steps.

The step result aggregates the per-document outcomes:

{
  "perDocument": true,
  "documents": [
    { "documentFamilyId": "...", "status": "COMPLETED", "action": "posted", "statusCode": 200 },
    { "documentFamilyId": "...", "status": "FAILED", "statusCode": 502, "error": "..." }
  ]
}

In the activity status dialog’s Activity Steps tab, a per-document step shows individual document status pills when four or fewer documents are routed, and a completed/total progress bar for larger fan-outs. When routing is in effect, an activity-level banner reports any unrouted documents whose resolved action matched no outgoing branch.

perDocument is only supported on EXECUTION, LLM, SCRIPT, and BRIDGE_CALL steps. Setting it on any other step kind is a plan validation error.

Error Handling

Use treatAsError when a successful HTTP response should still fail the step.

{
  "treatAsError": "$.status = 'rejected' or $.error != null"
}

The Activity can then be retried from the failed step after the upstream issue is fixed. Design bridge calls to be idempotent. Activities can be retried, and triggers can fire more than once in at-least-once workflows. External endpoints should tolerate duplicate request IDs or use a stable idempotency key from Activity inputs.

Security and Binding

Service Bridges are project resources. A BRIDGE_CALL step can only use bridges that are available to the project running the Activity. This gives the platform a clear boundary:

The Activity Plan defines the workflow.
The project binding defines which bridges are allowed.
The bridge configuration owns authentication and endpoint details.
The step owns request data, routing, and result handling for this business process.

Do not put secrets in Activity Plan step config. Use Service Bridge authentication settings and organization secrets instead.

BRIDGE_CALL vs SCRIPT with serviceBridge.call()

Requirement	Better fit
One external call should be visible and retryable as its own step	`BRIDGE_CALL`
Several external calls feed one custom decision	`SCRIPT`
Request mapping is straightforward	`BRIDGE_CALL`
The call should mutate documents before deciding the branch	`SCRIPT`
Operators need to see the external call status directly	`BRIDGE_CALL`

Next Steps

Activity Plan Steps

See how bridge steps fit with CREATE_TASK, SCRIPT, EXECUTION, and LLM steps.

Calling Service Bridges from Scripts

Use serviceBridge.call() from scripts, formulas, and event subscriptions.

Introduction

Activity Plans

Triggers

Task Templates

Task Groups

MCP Connector

Data Definitions

Excel Processing

Scripting

Intakes

Formulas

Project Templates

Data Forms

Working with Claude Code

Working with Kodexa Agent

Reference

When to Use a BRIDGE_CALL Step

Step Configuration

How It Runs

Request Mapping

Response Routing

Per-Document Bridge Calls

Error Handling

Security and Binding

BRIDGE_CALL vs SCRIPT with serviceBridge.call()

Next Steps

Activity Plan Steps

Calling Service Bridges from Scripts

​When to Use a BRIDGE_CALL Step

​Step Configuration

​How It Runs

​Request Mapping

​Response Routing

​Per-Document Bridge Calls

​Error Handling

​Security and Binding

​BRIDGE_CALL vs SCRIPT with serviceBridge.call()

​Next Steps

Activity Plan Steps

Calling Service Bridges from Scripts

When to Use a BRIDGE_CALL Step

Step Configuration

How It Runs

Request Mapping

Response Routing

Per-Document Bridge Calls

Error Handling

Security and Binding

BRIDGE_CALL vs SCRIPT with serviceBridge.call()

Next Steps