The bridge API provides scripts running inside the QuickJS sandbox with controlled access to Kodexa platform capabilities. Every bridge method is gated by a permission that must be declared in the form’s bridge.permissions array. If a script calls a method whose permission is not granted, the call throws a Permission denied error.
The bridge is organized into five namespaces: kodexa.data for reading and writing data objects and attributes, kodexa.navigation for controlling the workspace view, kodexa.form for managing form-level state, kodexa.http for making API requests, and kodexa.log for diagnostic output.
This page is a complete reference. For a guided introduction to scripting and the bridge, see the Scripting guide.
Permission Table
Every bridge method requires a specific permission. Declare the permissions your form needs in the bridge configuration:
{
"bridge": {
"permissions": ["data:read", "data:write", "navigation", "formState", "http:get", "http:post"]
}
}
| Permission | Methods |
|---|
data:read | kodexa.data.getDataObjects, getDataObject, getAttributes, getAttribute, getTagMetadata, getTaxonomies |
data:write | kodexa.data.setAttribute, addDataObject, deleteDataObject |
navigation | kodexa.navigation.focusAttribute, scrollToNode, switchView |
formState | kodexa.form.get, set, getNodeRef |
http:get | kodexa.http.get |
http:post | kodexa.http.post |
kodexa.log methods (debug, warn, error) do not require any permission and are always available.
kodexa.data
Methods for reading and writing data objects, attributes, and taxonomy metadata. These operate against the current workspace store.
getDataObjects
Returns an array of data objects, optionally filtered by path or parent ID.
kodexa.data.getDataObjects(filter?: { path?: string; parentId?: string }): DataObject[]
| Parameter | Type | Required | Description |
|---|
filter | object | No | Optional filter object |
filter.path | string | No | Filter by data object path (e.g., "invoice", "lineItem") |
filter.parentId | string | No | Filter by parent data object UUID |
data:read
{
"type": "script",
"target": "kodexa.log.debug('Invoices:', kodexa.data.getDataObjects({ path: 'invoice' }).length)"
}
getDataObject
Returns a single data object by UUID, or null if not found.
kodexa.data.getDataObject(uuid: string): DataObject | null
| Parameter | Type | Required | Description |
|---|
uuid | string | Yes | The UUID of the data object |
data:read
getAttributes
Returns all attributes for a given data object.
kodexa.data.getAttributes(dataObjectUuid: string): DataAttribute[]
| Parameter | Type | Required | Description |
|---|
dataObjectUuid | string | Yes | The UUID of the data object |
data:read
getAttribute
Returns the value of a specific attribute on a data object, or undefined if not found.
kodexa.data.getAttribute(dataObjectUuid: string, path: string): any
| Parameter | Type | Required | Description |
|---|
dataObjectUuid | string | Yes | The UUID of the data object |
path | string | Yes | The attribute path (e.g., "invoice/totalAmount") |
data:read
{
"type": "script",
"target": "kodexa.log.debug('Total:', kodexa.data.getAttribute(ctx.$item.uuid, 'invoice/totalAmount'))"
}
setAttribute
Sets the value of a specific attribute on a data object.
kodexa.data.setAttribute(dataObjectUuid: string, path: string, value: any): void
| Parameter | Type | Required | Description |
|---|
dataObjectUuid | string | Yes | The UUID of the data object |
path | string | Yes | The attribute path |
value | any | Yes | The new value to set |
data:write
{
"type": "script",
"target": "kodexa.data.setAttribute(ctx.$item.uuid, 'invoice/status', 'approved')"
}
addDataObject
Creates a new data object as a child of the specified parent.
kodexa.data.addDataObject(parentUuid: string, path: string): DataObject
| Parameter | Type | Required | Description |
|---|
parentUuid | string | Yes | The UUID of the parent data object |
path | string | Yes | The path (type) of the new data object (e.g., "lineItem") |
data:write
deleteDataObject
Deletes a data object by UUID.
kodexa.data.deleteDataObject(uuid: string): void
| Parameter | Type | Required | Description |
|---|
uuid | string | Yes | The UUID of the data object to delete |
data:write
Returns tag metadata for a given taxonomy path, or null if not found.
kodexa.data.getTagMetadata(path: string): TagMetadata | null
| Parameter | Type | Required | Description |
|---|
path | string | Yes | The taxonomy path (e.g., "invoice/totalAmount") |
data:read
getTaxonomies
Returns all taxonomies available in the current project.
kodexa.data.getTaxonomies(): Taxonomy[]
data:read
kodexa.navigation
Methods for controlling the workspace view and navigating to specific elements.
focusAttribute
Scrolls to and highlights a specific attribute in the document view.
kodexa.navigation.focusAttribute(dataObjectUuid: string, attributePath: string): void
| Parameter | Type | Required | Description |
|---|
dataObjectUuid | string | Yes | The UUID of the data object |
attributePath | string | Yes | The attribute path to focus |
navigation
{
"type": "script",
"target": "kodexa.navigation.focusAttribute(ctx.$item.uuid, 'invoice/invoiceNumber')"
}
ref name.
kodexa.navigation.scrollToNode(ref: string): void
| Parameter | Type | Required | Description |
|---|
ref | string | Yes | The ref value of the target UINode |
navigation
switchView
Switches the workspace to a different named view.
kodexa.navigation.switchView(viewName: string): void
| Parameter | Type | Required | Description |
|---|
viewName | string | Yes | The name of the view to switch to |
navigation
Methods for reading and writing form-level state that persists across script evaluations within the same session.
get
Retrieves a value from the form state store.
kodexa.form.get(key: string): any
| Parameter | Type | Required | Description |
|---|
key | string | Yes | The state key |
formState
set
Stores a value in the form state store.
kodexa.form.set(key: string, value: any): void
| Parameter | Type | Required | Description |
|---|
key | string | Yes | The state key |
value | any | Yes | The value to store |
formState
{
"type": "script",
"target": "kodexa.form.set('selectedTab', 'details')"
}
getNodeRef
Returns a reference to a rendered UINode by its ref name, allowing programmatic prop updates.
kodexa.form.getNodeRef(ref: string): { setProps(props: Record<string, any>): void }
| Parameter | Type | Required | Description |
|---|
ref | string | Yes | The ref value of the target UINode |
formState
{
"type": "script",
"target": "kodexa.form.getNodeRef('statusLabel').setProps({ label: 'Updated!' })"
}
kodexa.http
Methods for making HTTP requests to the Kodexa API or external endpoints. The base URL defaults to "/api" but can be overridden in the bridge configuration.
get
Performs an HTTP GET request and returns the parsed JSON response.
kodexa.http.get(path: string): Promise<any>
| Parameter | Type | Required | Description |
|---|
path | string | Yes | The URL path, appended to apiBaseUrl |
http:get
{
"type": "script",
"target": "kodexa.http.get('/document-stores/' + ctx.storeId).then(r => kodexa.log.debug(r))"
}
post
Performs an HTTP POST request with a JSON body and returns the parsed JSON response.
kodexa.http.post(path: string, body: any): Promise<any>
| Parameter | Type | Required | Description |
|---|
path | string | Yes | The URL path, appended to apiBaseUrl |
body | any | Yes | The request body, serialized as JSON |
http:post
kodexa.log
Diagnostic logging methods that output to the browser developer console. These methods do not require any permission.
debug
Logs a debug message.
kodexa.log.debug(...args: any[]): void
[DataFormV2] ...args
warn
Logs a warning message.
kodexa.log.warn(...args: any[]): void
error
Logs an error message.
kodexa.log.error(...args: any[]): void
Example
{
"events": {
"change": {
"type": "script",
"target": "kodexa.log.debug('Attribute changed:', ctx.$item?.uuid, 'new value:', ctx.newValue)"
}
}
}
Common Patterns
Read-Only Data Display
For forms that only display data, grant minimal permissions:
{
"bridge": {
"permissions": ["data:read"]
}
}
{
"bridge": {
"permissions": ["data:read", "data:write", "navigation", "formState"]
}
}
{
"bridge": {
"permissions": ["data:read", "http:get", "http:post"],
"apiBaseUrl": "/api"
}
}
Next Steps
