Bridge API & External Services

The Bridge API is the interface between scripts running in the QuickJS sandbox and the Kodexa platform. Scripts access it through the kodexa.* namespace, where each sub-namespace corresponds to a capability gated by the form’s bridge permissions.

Bridge Permissions

The bridge property on a data form configures what scripts are allowed to do. The permissions array lists capability gates — a script that attempts to call a method without the required permission will receive a Permission denied error.

Permission	Grants access to
`data:read`	Read data objects, attributes, tag metadata, taxonomies
`data:write`	Modify data objects and attributes
`document:read`	Access the document proxy (`kodexa.document`)
`navigation`	Focus attributes, scroll to nodes, switch views
`formState`	Get and set form state values, access node refs
`http:get`	HTTP GET requests via `kodexa.http`
`http:post`	HTTP POST requests via `kodexa.http` and service bridge calls

Additional bridge configuration:

apiBaseUrl — Base URL for kodexa.http and kodexa.serviceBridge calls. Defaults to "/api".
maxExecutionMs — Script execution timeout in milliseconds. Defaults to 1000.

{
  "bridge": {
    "permissions": ["data:read", "data:write", "navigation", "http:post"],
    "apiBaseUrl": "https://api.example.com",
    "maxExecutionMs": 2000
  }
}

kodexa.data

Requires data:read. Methods that modify data also require data:write.

Method	Parameters	Returns	Permission
`getDataObjects(filter?)`	`{ path?: string, parentId?: string }`	`DataObject[]`	`data:read`
`getDataObject(uuid)`	`uuid: string`	`DataObject \| null`	`data:read`
`getAttributes(dataObjectUuid)`	`dataObjectUuid: string`	`Attribute[]`	`data:read`
`getAttribute(dataObjectUuid, path)`	`dataObjectUuid: string, path: string`	`any`	`data:read`
`setAttribute(dataObjectUuid, path, value)`	`dataObjectUuid: string, path: string, value: any`	`void`	`data:write`
`addDataObject(parentUuid, path)`	`parentUuid: string, path: string`	`DataObject`	`data:write`
`deleteDataObject(uuid)`	`uuid: string`	`void`	`data:write`
`getTagMetadata(path)`	`path: string`	`TagMetadata \| null`	`data:read`
`getTaxonomies()`	—	`Taxonomy[]`	`data:read`

// Read all line items under a parent object
const items = kodexa.data.getDataObjects({ parentId: parentUuid });
for (const item of items) {
  const amount = kodexa.data.getAttribute(item.uuid, "LineItem/Amount");
  kodexa.log.debug("Amount: " + amount);
}

// Set a computed total
kodexa.data.setAttribute(summaryUuid, "Invoice/Total", calculatedTotal);

Requires navigation.

Method	Parameters	Description
`focusAttribute(dataObjectUuid, attributePath)`	`dataObjectUuid: string, attributePath: string`	Highlight an attribute in the document viewer
`scrollToNode(ref)`	`ref: string`	Scroll the document viewer to a content node
`switchView(viewName)`	`viewName: string`	Switch to a different form view

Note that focusAttribute takes dataObjectUuid as the first parameter and attributePath as the second.

kodexa.form

Requires formState.

Method	Parameters	Returns	Description
`get(key)`	`key: string`	`any`	Read a form state value
`set(key, value)`	`key: string, value: any`	`void`	Write a form state value
`getNodeRef(ref)`	`ref: string`	`{ setProps(props) }`	Get a UINode by ref for dynamic prop updates

Form state is ephemeral — it persists for the lifetime of the form session but is not saved to the server. Use it for UI-only concerns like toggling visibility, tracking selection state, or passing values between scripts.

// Toggle a detail panel
const expanded = kodexa.form.get("detailExpanded") || false;
kodexa.form.set("detailExpanded", !expanded);

// Dynamically update a node's props
const node = kodexa.form.getNodeRef("statusLabel");
node.setProps({ text: "Validated", variant: "success" });

kodexa.document

Requires document:read. The writable snapshot also requires data:write.

Method	Returns	Description
`snapshot()`	`ScriptDocumentProxy`	Read-only proxy over the current document data
`writableSnapshot()`	`ScriptDocumentProxy`	Writable proxy — mutations flow through the workspace store

The ScriptDocumentProxy exposes getAllDataObjects(), getDataObjectByUUID(uuid), and getDataObjectsByPath(path). Each returns ScriptDataObjectProxy instances with methods like getAttributes(), getAttribute(label), getChildren(), and getPath(). Writable proxies additionally support addAttribute(), addChild(), and setValue() on attributes. This API is separate from loadDocument() available in inline or named scripts. kodexa.document provides Bridge API context tied to the current workspace session; loadDocument() is for standalone script execution.

kodexa.http

Requires http:get for GET requests, http:post for POST requests. Both are async.

Method	Parameters	Returns
`get(path)`	`path: string`	`Promise<any>`
`post(path, body?)`	`path: string, body?: any`	`Promise<any>`

Requests are sent to apiBaseUrl + path. The base URL defaults to "/api" if not configured.

// Call an external validation endpoint
const result = await kodexa.http.post("/validate", {
  invoiceNumber: invoiceNum,
  vendorId: vendorId
});

if (!result.valid) {
  kodexa.log.warn("Validation failed: " + result.reason);
}

kodexa.serviceBridge

Requires http:post.

Method	Parameters	Returns
`call(ref, endpoint, body?)`	`ref: string, endpoint: string, body?: any`	`Promise<any>`

Service bridges are named proxy endpoints that connect the platform to external APIs with centralized authentication. The ref is the bridge slug (e.g., "cass-freight/data-entry-automation"), and endpoint is the endpoint name defined in the bridge YAML. The bridge manages an X-Bridge-Context header for session caching. On the first call, no context header is sent; the server runs any configured initScript and returns context in the response header. Subsequent calls attach the cached context, skipping re-initialization. Context expires after a configurable TTL (default 3600 seconds).

const carriers = await kodexa.serviceBridge.call(
  "cass-freight/data-entry-automation",
  "lookup-carrier",
  { scac: scacCode }
);

kodexa.log

No permission required.

Method	Parameters
`debug(message)`	`message: string`
`warn(message)`	`message: string`
`error(message)`	`message: string`

All log output is prefixed with [DataFormV2] and routed to the browser console.

Service Bridges on Panels

In addition to imperative kodexa.serviceBridge.call() from scripts, panels support declarative service bridge integration through the serviceBridge prop on v2:panel. This allows a component to declare an external API dependency without writing script code.

ServiceBridgeConfig

Property	Type	Description
`ref`	`string`	Bridge reference (e.g., `"cass-freight/data-entry-automation"`)
`endpoint`	`string`	Endpoint name from the bridge YAML
`method`	`"GET" \| "POST"`	HTTP method, defaults to `POST`
`requestMapping`	`Record<string, string>`	Maps data attribute paths to request fields
`responseMapping`	`ServiceBridgeResponseMapping`	Controls how the response maps back to UI or data
`triggerOn`	`string[]`	Attribute paths that trigger a re-call when values change

ServiceBridgeResponseMapping

Property	Type	Description
`value`	`string`	Path to extract option value from each response item
`label`	`string`	Path or expression for the option label (supports concatenation like `"code + ' - ' + description"`)
`description`	`string`	Path or expression for hint text shown below the label in dropdowns
`autoSelect`	`string`	Auto-select a single best-match field from the response
`attributes`	`Array<{ from, to }>`	Map response fields to data attributes (`from`: response path, `to`: attribute path)

How It Works

When any attribute listed in triggerOn changes, the panel reads the current values from requestMapping, calls the service bridge endpoint, and maps the response back using responseMapping. This creates a reactive loop: user edits a field, the bridge fetches updated data, and dependent fields populate automatically.

{
  "component": "v2:panel",
  "props": {
    "title": "Carrier Details",
    "serviceBridge": {
      "ref": "cass-freight/data-entry-automation",
      "endpoint": "lookup-carrier",
      "requestMapping": {
        "scac": "Shipment/CarrierSCAC"
      },
      "responseMapping": {
        "value": "carrierId",
        "label": "scac + ' - ' + carrierName",
        "attributes": [
          { "from": "carrierName", "to": "Shipment/CarrierName" },
          { "from": "dotNumber", "to": "Shipment/DOTNumber" }
        ]
      },
      "triggerOn": ["Shipment/CarrierSCAC"]
    }
  }
}

In this example, when the user enters a SCAC code, the panel calls the carrier lookup endpoint and auto-populates the carrier name and DOT number fields from the response.

Introduction

Data Definitions

Script Steps

Scheduled Jobs

Intakes

Large Document Processing

Formulas

Project Templates

Data Forms

Reference

Bridge Permissions

kodexa.data

kodexa.navigation

kodexa.form

kodexa.document

kodexa.http

kodexa.serviceBridge

kodexa.log

Service Bridges on Panels

ServiceBridgeConfig

ServiceBridgeResponseMapping

How It Works

Introduction

Data Definitions

Script Steps

Scheduled Jobs

Intakes

Large Document Processing

Formulas

Project Templates

Data Forms

Reference

​Bridge Permissions

​kodexa.data

​kodexa.navigation

​kodexa.form

​kodexa.document

​kodexa.http

​kodexa.serviceBridge

​kodexa.log

​Service Bridges on Panels

​ServiceBridgeConfig

​ServiceBridgeResponseMapping

​How It Works

Bridge Permissions

kodexa.data

kodexa.navigation

kodexa.form

kodexa.document

kodexa.http

kodexa.serviceBridge

kodexa.log

Service Bridges on Panels

ServiceBridgeConfig

ServiceBridgeResponseMapping

How It Works