Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt

Use this file to discover all available pages before exploring further.

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",
  "kind": "BRIDGE_CALL",
  "dependsOn": ["analyst-review:approved"],
  "config": {
    "serviceBridgeRef": "finance-erp",
    "endpointName": "post-invoice",
    "requestBody": {
      "documentFamilyId": "{{inputs.documentFamilyId}}",
      "sourceSystem": "{{inputs.sourceSystem}}"
    },
    "treatAsError": "$.status != 'accepted'",
    "timeoutSeconds": 30,
    "disableCache": true
  }
}
Config keyDescription
serviceBridgeRefService Bridge slug or ref
endpointNameEndpoint defined by the bridge
requestBodyStatic body, template, or expression that builds the JSON request
requestQueryOptional query-string template
requestPathOptional path substitution
requestHeadersOptional request headers, excluding secrets
requestScriptOptional JavaScript preprocessor for complex request construction
bridgeActionsActions the bridge response can emit for downstream routing
treatAsErrorPredicate that marks a response as a failed step
timeoutSecondsPer-call timeout
disableCacheWhether 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",
  "kind": "BRIDGE_CALL",
  "config": {
    "serviceBridgeRef": "finance-reference-data",
    "endpointName": "validate-supplier",
    "requestBody": {
      "supplierId": "{{inputs.supplierId}}"
    },
    "bridgeActions": [
      {
        "name": "valid",
        "when": "$.valid = true"
      },
      {
        "name": "review",
        "when": "$.valid != true"
      }
    ]
  }
}
Then route downstream work: 
{
  "slug": "supplier-review",
  "kind": "CREATE_TASK",
  "dependsOn": ["validate-supplier:review"],
  "config": {
    "taskTemplateRef": "supplier-exception-review"
  }
}

​
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()

RequirementBetter fit
One external call should be visible and retryable as its own stepBRIDGE_CALL
Several external calls feed one custom decisionSCRIPT
Request mapping is straightforwardBRIDGE_CALL
The call should mutate documents before deciding the branchSCRIPT
Operators need to see the external call status directlyBRIDGE_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.