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, switch pages, rotate pages, switch views (`kodexa.navigation`)
`viewer`	Scroll, pan, zoom, and pop out / re-dock the spatial document viewer (`kodexa.viewer`)
`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. Spatial-viewer methods route to the document viewer for the form’s first document family by default; pass an explicit documentFamilyId when a form is bound to more than one document.

Method	Parameters	Returns	Description
`focusAttribute(dataObjectUuid, attributePath, viewId?)`	`dataObjectUuid: string, attributePath: string, viewId?: string`	`void`	Highlight an attribute in the document viewer (and broadcast to sidecars)
`setPage(page, documentFamilyId?)`	`page: number, documentFamilyId?: string`	`void`	Navigate the spatial viewer to a 1-based page number
`nextPage(documentFamilyId?)`	`documentFamilyId?: string`	`void`	Step the spatial viewer forward one page. Clamped to the last page — a no-op at the end of the document
`previousPage(documentFamilyId?)`	`documentFamilyId?: string`	`void`	Step the spatial viewer back one page. Clamped to the first page — a no-op at the start of the document
`rotatePage(direction, documentFamilyId?)`	`direction: "left" \| "right", documentFamilyId?: string`	`void`	Rotate the spatial viewer’s current page by 90° in the given direction
`getCurrentPage(documentFamilyId?)`	`documentFamilyId?: string`	`number \| undefined`	Current 1-based page of the spatial viewer
`getPageCount(documentFamilyId?)`	`documentFamilyId?: string`	`number \| undefined`	Total page count of the spatial viewer’s document
`scrollToNode(ref)`	`ref: string`	`void`	Scroll the document viewer to a content node (planned)
`switchView(viewName)`	`viewName: string`	`void`	Switch to a different form view (planned)

Note that focusAttribute takes dataObjectUuid as the first parameter and attributePath as the second. rotatePage behaves differently from the absolute setPage:

Rotation is relative. Each call rotates by ±90° from the page’s current rotation — it is not an absolute angle. Calling rotatePage("right") twice leaves the page at 180°; a following rotatePage("left") returns it to 90°.
It affects only the current page. Rotating every page of the document remains a separate viewer menu action; the bridge method touches just the page the viewer is currently showing.
It requires the navigation permission and accepts an optional documentFamilyId to target a specific open document when the form is bound to more than one. A per-document rotation does not bleed across documents.

An invalid direction (anything other than "left" or "right") or a missing viewer is a no-op — a warning is logged to the browser console and no error is thrown.

// Jump to page 3 of the form's document
kodexa.navigation.setPage(3);

// Step one page at a time -- these clamp at the document edges,
// so calling nextPage() on the last page (or previousPage() on
// the first) is a silent no-op rather than an error.
kodexa.navigation.nextPage();
kodexa.navigation.previousPage();

// Read the current page after a navigation
const current = kodexa.navigation.getCurrentPage();
kodexa.log.debug("Now on page " + current + " of " + kodexa.navigation.getPageCount());

// Target a specific document when the form is bound to multiple
kodexa.navigation.setPage(1, "doc-family-uuid");

// Rotate the current page of the form's document clockwise
kodexa.navigation.rotatePage("right");

// Rotate a specific open document's current page counter-clockwise
kodexa.navigation.rotatePage("left", "doc-family-uuid");

These rotate actions are typically wired to keyboard shortcuts rather than called directly. The alt+R / alt+shift+R bindings are not hard-coded — they are authored declaratively as form shortcuts entries whose script calls kodexa.navigation.rotatePage(...):

shortcuts:
  - key: "alt+r"
    description: "Rotate the current page right"
    scriptRef: rotate-page-right
  - key: "alt+shift+r"
    description: "Rotate the current page left"
    scriptRef: rotate-page-left

The rotate-page-right script calls kodexa.navigation.rotatePage("right") and rotate-page-left calls kodexa.navigation.rotatePage("left"), so a shortcuts: block round-trips through the data form schema.

kodexa.viewer

Requires viewer. The viewer surface manipulates the spatial document viewport — its scroll and pan position, its zoom level, and whether the viewer is docked in the workspace or popped out into its own browser tab — rather than the page state. That separation is why it is a distinct permission from navigation.

Method	Parameters	Returns	Description
`scroll(direction, documentFamilyId?)`	`direction: "up" \| "down" \| "left" \| "right", documentFamilyId?: string`	`void`	Nudge the spatial viewer ~¼ of its visible size in the given direction
`zoom(direction, documentFamilyId?)`	`direction: "in" \| "out", documentFamilyId?: string`	`void`	Zoom the spatial viewer in or out one step, matching the toolbar zoom buttons
`detach()`	—	`void`	Pop the viewer out into a new browser tab, mirroring the viewer’s “Open in new tab” button
`dock()`	—	`void`	Dock a popped-out viewer back into the workspace, mirroring the viewer’s “Dock back to workspace” button

scroll direction is one of "up", "down", "left", "right". Any other value is a no-op — a warning is logged to the browser console and no error is thrown. "up" / "down" scroll the viewer vertically; "left" / "right" pan the zoom transform (the spatial image is CSS-transformed, so left/right movement pans rather than scrolls). Both feel like a small “arrow key” nudge, not a full-screen jump.
zoom steps one increment in or out. "in" and "out" map to the toolbar’s zoom-in / zoom-out buttons — one call is one step. Any other value is a no-op with a browser-console warning and no error thrown.
detach pops the viewer out into a new browser tab. This is the same action as the viewer’s “Open in new tab” button. It is only meaningful from the main window — calling it from inside the popped-out tab is a no-op (a warning is logged). If the pop-out tab is already open, detach focuses that tab rather than opening a second one. It takes no arguments.
dock returns a popped-out viewer to the workspace. This mirrors the viewer’s “Dock back to workspace” button and works from either the main window or the popped-out tab. When no viewer is currently detached it is a no-op with a warning. It takes no arguments.
scroll and zoom can target one document. With no argument they act on the form’s default (first) document family; pass an optional documentFamilyId to target a specific open document. Both apply to the viewer whether it is docked or popped out. detach and dock always act on the workspace’s pop-out viewer and take no target.
Requires the viewer permission. Calling any kodexa.viewer method without "viewer" in bridge.permissions throws a Permission denied: viewer error.

// Nudge the viewer down, then pan right
kodexa.viewer.scroll("down");
kodexa.viewer.scroll("right");

// Zoom in one step, then back out
kodexa.viewer.zoom("in");
kodexa.viewer.zoom("out");

// Pop the viewer out into its own tab, then dock it back
kodexa.viewer.detach();
kodexa.viewer.dock();

// scroll and zoom accept a documentFamilyId to target a specific open document
kodexa.viewer.scroll("up", "doc-family-uuid");
kodexa.viewer.zoom("in", "doc-family-uuid");

Like the rest of the Bridge API, these actions are usually wired to keyboard shortcuts rather than called directly. Bindings are authored declaratively as form shortcuts entries (see Keyboard Shortcuts); zoom, detach, and dock fit the "zoom" help-dialog group. The keys below are only examples chosen by the form author — there are no fixed hotkeys for these actions:

shortcuts:
  - key: "control+="
    description: "Zoom the document in"
    group: "zoom"
    scriptRef: zoom-in
  - key: "control+-"
    description: "Zoom the document out"
    group: "zoom"
    scriptRef: zoom-out
  - key: "control+9"
    description: "Open the viewer in a new tab"
    group: "zoom"
    scriptRef: detach-viewer
  - key: "control+w"
    description: "Dock the viewer back to the workspace"
    group: "zoom"
    scriptRef: dock-viewer

Each scriptRef points at a script that calls the matching method — for example detach-viewer calls kodexa.viewer.detach() and dock-viewer calls kodexa.viewer.dock().

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., "acme-logistics/carrier-lookup"), 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(
  "acme-logistics/carrier-lookup",
  "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., `"acme-logistics/carrier-lookup"`)
`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": "acme-logistics/carrier-lookup",
      "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.

v2:serviceBridgeView

A container component that calls a service bridge endpoint and makes the response available to its children through the data context. Unlike the panel serviceBridge prop (which maps responses back to attributes), v2:serviceBridgeView is designed for read-only display — rendering bridge responses as tables, markdown, labels, or any combination of child components.

How It Works

The component resolves the bridge slug to an ID via the platform’s /api/resolve endpoint.
It POSTs the params to the bridge proxy endpoint (/api/service-bridges/{id}/proxy/{endpoint}).
If a transform expression is provided, the response is reshaped using JSONata.
The result is injected into a scoped DataContextV2 as ctx.$bridgeResult, along with ctx.$bridgeLoading and ctx.$bridgeError.
Children render using bindings that reference these context variables.

The component handles loading and error states automatically — children are only rendered once data is available.

Props

Prop	Type	Default	Description
bridgeRef	string	required	Service bridge URI (e.g., `"service-bridge://acme/rate-lookup"` or `"acme/rate-lookup"`)
endpoint	string	required	Endpoint name defined in the bridge configuration
params	Record	—	Request body sent to the bridge (typically provided via `bindings`)
transform	string	—	JSONata expression applied to the response before injecting into context

Context Variables

Children of v2:serviceBridgeView receive these additional context variables:

Variable	Type	Description
`ctx.$bridgeResult`	`any`	The bridge response (after optional JSONata transform)
`ctx.$bridgeLoading`	`boolean`	`true` while the request is in flight
`ctx.$bridgeError`	`string`	Error message if the request failed

All existing context variables (ctx.dataObjects, ctx.tagMetadataMap, etc.) remain available — the bridge context is additive.

Reactive Parameters

When params is provided via bindings, the component re-calls the bridge whenever the bound values change. This creates a reactive chain: the user edits an attribute, the binding expression re-evaluates, new params are sent to the bridge, and children re-render with fresh data.

When referencing attributes in binding expressions, the tag property is the leaf name (e.g., originZip), not the full taxonomy path (shipment/originZip). The full path is available as path on the attribute. Use a.tag === 'originZip' or a.path === 'shipment/originZip' depending on which you need.

Example: Table from Bridge Response

Call a rate lookup endpoint, transform the response with JSONata, and render the results as a filterable AG Grid table:

component: v2:serviceBridgeView
props:
  bridgeRef: "service-bridge://acme/rate-lookup"
  endpoint: "get-rates"
  transform: |
    results.{
      "Carrier": carrier,
      "Rate": "$" & $string(rate),
      "Transit": transit & " days"
    }
bindings:
  params: |
    {
      originZip: ctx.dataObjects[0]?.attributes?.find(
        a => a.tag === 'originZip'
      )?.stringValue,
      destZip: ctx.dataObjects[0]?.attributes?.find(
        a => a.tag === 'destZip'
      )?.stringValue,
      weight: ctx.dataObjects[0]?.attributes?.find(
        a => a.tag === 'weight'
      )?.numericValue
    }
children:
  - component: v2:dataTable
    bindings:
      rows: "ctx.$bridgeResult"
    props:
      filterable: true
      columns:
        - field: Carrier
          title: Carrier Name
        - field: Rate
          title: Rate
          width: 120
        - field: Transit
          title: Transit Time
          width: 120

Example: Markdown Summary

Fetch a report from a bridge and render it as markdown:

component: v2:serviceBridgeView
props:
  bridgeRef: "service-bridge://acme/analysis"
  endpoint: "get-report"
bindings:
  params: |
    {
      invoiceId: ctx.dataObjects[0]?.attributes?.find(
        a => a.tag === 'id'
      )?.stringValue
    }
children:
  - component: v2:markdown
    bindings:
      content: "ctx.$bridgeResult?.report"

Example: Mixed Content

Combine multiple child components to render different parts of the bridge response:

component: v2:serviceBridgeView
props:
  bridgeRef: "service-bridge://acme/vendor-check"
  endpoint: "validate"
bindings:
  params: |
    {
      vendorCode: ctx.dataObjects[0]?.attributes?.find(
        a => a.tag === 'vendorCode'
      )?.stringValue
    }
children:
  - component: v2:label
    bindings:
      text: "'Vendor: ' + (ctx.$bridgeResult?.vendorName ?? 'Unknown')"
  - component: v2:dataTable
    bindings:
      rows: "ctx.$bridgeResult?.recentOrders"
    props:
      filterable: true
      columns:
        - field: orderNumber
          title: Order #
        - field: date
          title: Date
        - field: amount
          title: Amount
  - component: v2:markdown
    bindings:
      content: "ctx.$bridgeResult?.notes"

JSONata Transform Reference

The transform prop accepts any valid JSONata expression. Common patterns:

Pattern	Expression	Description
Extract a nested array	`response.data.items`	Drill into the response structure
Reshape objects	`items.{ "Name": name, "Total": "$" & $string(price * qty) }`	Create new fields from existing ones
Filter rows	`items[status = "active"]`	Only include rows matching a condition
Aggregate	`$sum(items.amount)`	Compute totals or other aggregations
Sort	`items^(>amount)`	Sort results by a field
String formatting	`items.{ "Display": firstName & " " & lastName }`	Concatenate fields

If the transform is omitted, the raw response is passed through as ctx.$bridgeResult.

The JSONata transform runs client-side after the response is received. For large responses, consider using the bridge’s postReplyScript to filter server-side before the data reaches the browser.

Comparison: Panel serviceBridge vs serviceBridgeView

Feature	Panel `serviceBridge` prop	`v2:serviceBridgeView`
Purpose	Map bridge response to data attributes	Display bridge response as read-only content
Trigger	Attribute path changes (`triggerOn`)	Binding expression changes (reactive params)
Response handling	`responseMapping` writes to attributes	Children render from `ctx.$bridgeResult`
Rendering	No built-in display	Children render tables, markdown, labels, etc.
Script required	No	No
Use case	Auto-populate fields from external data	Show reference data, reports, lookup tables

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

Bridge Permissions

kodexa.data

kodexa.navigation

kodexa.viewer

kodexa.form

kodexa.document

kodexa.http

kodexa.serviceBridge

kodexa.log

Service Bridges on Panels

ServiceBridgeConfig

ServiceBridgeResponseMapping

How It Works

v2:serviceBridgeView

How It Works

Props

Context Variables

Reactive Parameters

Example: Table from Bridge Response

Example: Markdown Summary

Example: Mixed Content

JSONata Transform Reference

Comparison: Panel serviceBridge vs serviceBridgeView

​Bridge Permissions

​kodexa.data

​kodexa.navigation

​kodexa.viewer

​kodexa.form

​kodexa.document

​kodexa.http

​kodexa.serviceBridge

​kodexa.log

​Service Bridges on Panels

​ServiceBridgeConfig

​ServiceBridgeResponseMapping

​How It Works

​v2:serviceBridgeView

​How It Works

​Props

​Context Variables

​Reactive Parameters

​Example: Table from Bridge Response

​Example: Markdown Summary

​Example: Mixed Content

​JSONata Transform Reference

​Comparison: Panel serviceBridge vs serviceBridgeView

Bridge Permissions

kodexa.data

kodexa.navigation

kodexa.viewer

kodexa.form

kodexa.document

kodexa.http

kodexa.serviceBridge

kodexa.log

Service Bridges on Panels

ServiceBridgeConfig

ServiceBridgeResponseMapping

How It Works

v2:serviceBridgeView

How It Works

Props

Context Variables

Reactive Parameters

Example: Table from Bridge Response

Example: Markdown Summary

Example: Mixed Content

JSONata Transform Reference

Comparison: Panel serviceBridge vs serviceBridgeView