Skip to main content
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 all execution contexts — script steps, event subscriptions, and selection option formulas.

​
The serviceBridge.call() API

var result = serviceBridge.call(bridgeRef, endpointName, body);
Parameters:
ParameterTypeRequiredDescription
bridgeRefstringYesService bridge reference. Format: "orgSlug/bridgeSlug" or just "bridgeSlug" (uses current org)
endpointNamestringYesName of the endpoint defined in the bridge configuration
bodyobjectNoRequest 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");
}

​
The serviceBridge.list() API

var bridges = serviceBridge.list();
Returns an array of available bridges: 
[
  {
    slug: "myorg/hr-system",
    name: "HR System",
    endpoints: [
      { name: "list-departments", method: "POST", path: "/api/departments" },
      { name: "get-employee", method: "POST", path: "/api/employees" }
    ]
  }
]
serviceBridge.list() is available in script steps and orchestrator contexts. In event subscriptions running in the browser (WASM), list returns an error — use serviceBridge.call() directly with known bridge references.

​
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

LimitValue
Max calls per execution10 service bridge calls per script run
Per-call timeout30 seconds
Response size limit10 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") {
  bridge.data.setAttribute(currentObject.GetID(), "employee_status", "Verified");
} else {
  bridge.data.setAttribute(currentObject.GetID(), "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) {
    var nameAttr = record.GetAttributeByName("applicant_name");
    if (nameAttr) {
      nameAttr.SetStringValue(details.fullName);
    }
  }
}

doc.Close();
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

To create and configure service bridges (endpoints, authentication, caching), see Service Bridges in Studio.