Calling Service Bridges from Scripts

Service bridges are pre-configured API proxies that scripts can call to interact with external systems. Authentication credentials are managed centrally and never exposed to script code. Scripts call bridges through a unified serviceBridge.call() API that works identically across script steps, event subscriptions, and selection option formulas.

If the external call should be tracked as its own Activity step, use a Service Bridge step. Use serviceBridge.call() inside a script when the call is part of a larger custom decision.

The serviceBridge.call() API

var result = serviceBridge.call(bridgeRef, endpointName, body);

Parameters:

Parameter	Type	Required	Description
`bridgeRef`	string	Yes	Service bridge reference. Format: `"orgSlug/bridgeSlug"` or just `"bridgeSlug"` (uses current org)
`endpointName`	string	Yes	Name of the endpoint defined in the bridge configuration
`body`	object	No	Request body sent as JSON. Omit for GET requests

Return value: The parsed JSON response body from the external API. If the external API returns a null or empty response, the result is null. If the call fails due to a network error, misconfiguration, or timeout, a JavaScript exception is thrown. Use a try/catch block or check the return value. Example:

// Fetch a list of departments from an external HR system
var departments = serviceBridge.call(
  "myorg/hr-system",
  "list-departments",
  { region: "North America" }
);

if (departments && departments.length > 0) {
  log.info("Found " + departments.length + " departments");
}

How It Works

When a script calls serviceBridge.call(), the request is proxied through the Kodexa API. The API resolves the bridge slug, injects authentication headers configured on the bridge, and forwards the request to the external endpoint. The response flows back to the script as a parsed JSON object. The key security benefit: secrets never leave the server. Bridge credentials are injected by the API proxy layer, not by the script runtime. The proxy endpoint used internally is POST /api/service-bridges/{id}/proxy/{endpointName}.

Limits and Timeouts

Limit	Value
Max calls per execution	10 service bridge calls per script run
Per-call timeout	30 seconds
Response size limit	10 MB

Calls count toward the script’s overall execution timeout.

If a service bridge call fails (network error, timeout, misconfiguration), a JavaScript exception is thrown. If the external API returns an empty or null response, serviceBridge.call() returns null. Always guard with a try/catch block or null check.

Examples

Use a service bridge in a selection option formula to populate dynamic choices:

// In a selection option formula
var options = serviceBridge.call(
  "myorg/reference-data",
  "get-categories",
  { parentId: getAttribute("parent_category") }
);

// Return format expected: [{label: "Electronics", value: "ELEC"}, ...]
return options || [];

Validate against an external system

Use a service bridge in an event subscription to validate data as it changes:

// In an event subscription script
if (!currentObject) return;

var employeeId = currentObject.getFirstAttributeValue("employee_id");
if (!employeeId) return;

var employee = serviceBridge.call(
  "myorg/directory",
  "validate-employee",
  { id: employeeId }
);

if (employee && employee.status === "active") {
  currentObject.setAttribute("employee_status", "Verified");
} else {
  currentObject.setAttribute("employee_status", "Unknown");
}

Enrich data in a script step

Call an external system to pull in related data during document processing:

var doc = loadDocument(families[0].id);
var record = doc.findFirstDataObjectByPath("Application");

if (record) {
  var refNumber = record.getFirstAttributeValue("reference_number");

  var details = serviceBridge.call(
    "myorg/records-api",
    "get-record",
    { referenceNumber: refNumber }
  );

  if (details) {
    record.setAttribute("applicant_name", details.fullName);
  }
}

return { action: "enriched" };

Error Handling

Service bridge calls can fail in two ways: the call itself fails (throwing a JavaScript exception), or the external API returns a null/empty response. Handle both cases:

try {
  var result = serviceBridge.call("myorg/api", "endpoint", { data: "value" });

  if (result === null) {
    log.warn("Service bridge returned empty response; using fallback");
    // Handle empty response
  } else if (result.error) {
    log.error("API returned error:", result.error);
  } else {
    // Process result
  }
} catch (e) {
  log.error("Service bridge call failed:", e);
  // Handle network/config error gracefully
}

Log warnings when bridge calls fail so you can diagnose issues from the event activity log without breaking the overall script execution.

Setting Up Service Bridges

Service bridges are project resources with endpoint, authentication, and caching configuration. Configure them through the platform UI or resource files for the target project.

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

The serviceBridge.call() API

How It Works

Limits and Timeouts

Examples

Validate against an external system

Enrich data in a script step

Error Handling

Setting Up Service Bridges

​The serviceBridge.call() API

​How It Works

​Limits and Timeouts

​Examples

​Lookup data for a dropdown

​Validate against an external system

​Enrich data in a script step

​Error Handling

​Setting Up Service Bridges

The serviceBridge.call() API

How It Works

Limits and Timeouts

Examples

Lookup data for a dropdown

Validate against an external system

Enrich data in a script step

Error Handling

Setting Up Service Bridges