Calling Service Bridges from Scripts

Use the serviceBridge API in Kodexa scripts to call external systems through pre-configured API proxies with centralized authentication and policies.

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}.

Egress Restrictions

A service bridge may only reach publicly resolvable hosts. When the platform makes the outbound call — a BRIDGE_CALL Activity step, an agent call, or a data form lookup through the proxy — the destination is checked before any connection is made, and a target that resolves to a loopback, private, link-local, or cloud-metadata address is refused. Hostnames that are platform-internal by name, localhost among them, are refused the same way; the host’s address is pinned once it resolves; and every hop of a redirect chain is re-checked rather than followed blindly. OAuth token endpoints are checked alongside endpoint paths, so auth.tokenUrl must be publicly resolvable too.

A refused call through the proxy returns 400 with service bridge egress denied and the reason. A refused BRIDGE_CALL step fails with the same reason. If a bridge you call from a script is pointed at a private or in-cluster host, the fix is the bridge’s baseUrl — no script change makes the destination reachable.

Self-hosted deployments that must reach an internal mock or test service can set BRIDGE_EGRESS_PRIVATE_HOST_ALLOWLIST — a comma-separated list of exact hostnames — in the environment of both the API and the orchestrator. Matching is exact and case-insensitive, with no wildcards and no CIDR ranges; a redirect from an exempted host into any other private destination is still refused; and an active allowlist is logged as a warning at startup. It exists for development and test environments only.

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

Lookup data for a dropdown

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.