Script Steps in Activity Plans

A SCRIPT step runs JavaScript inside an Activity. It is the right tool when the workflow needs custom logic that is too specific for a declarative step. Script steps are commonly used to inspect documents, normalize extracted data, assign knowledge features, call Service Bridges, and decide which branch of the Activity Plan should run next.

When to Use a SCRIPT Step

Use a SCRIPT step when you need to:

Route the Activity based on document content, metadata, extraction results, or task status
Make several checks before deciding whether human review is needed
Update document metadata, labels, tags, data objects, or attributes
Assign knowledge features to document families
Call one or more Service Bridges and combine their responses
Emit a named action for downstream dependencies

Do not use a script just to make one external API call. Use a Service Bridge step for that so the external call has its own step status, logs, retry behavior, and result.

Step Configuration

{
  "slug": "route-invoice",
  "type": "SCRIPT",
  "dependsOn": ["extract"],
  "scriptActions": [
    { "slug": "review", "name": "review" },
    { "slug": "post",   "name": "post" },
    { "slug": "reject", "name": "reject" }
  ],
  "scriptSidecars": ["acme-finance/invoice-script-helpers"],
  "scriptBody": "return { action: 'review' };"
}

Step field	Description
`scriptBody`	Inline JavaScript source
`scriptActions`	Named actions the script can return
`scriptSidecars`	JavaScript module refs loaded before the script runs

The script must return an object with an action property when downstream routing depends on the step.

return { action: "review" };

Downstream steps can depend on that action:

{
  "slug": "analyst-review",
  "type": "CREATE_TASK",
  "dependsOn": ["route-invoice:review"]
}

Actions are identified by their slug. Downstream dependsOn entries use "step:actionSlug" to match a specific outcome. The action’s name is the value the script returns (e.g. return { action: "review" }) and the display label the runtime surfaces in logs. Older plans use a uuid field on each action — that is the legacy spelling of slug and still resolves, but new authoring should use slug.

Return Value

The full return value can carry three optional pieces alongside action:

return {
  action: "approve",
  features: [
    { documentFamilyId: families[0].id, featureId: "fc_billing_ready" }
  ],
  nextActivity: {
    activityPlanRef: "activity-plan://acme-finance/billing-extraction",
    inputs: { reviewedBy: org.userEmail }
  }
};

Field	Description
`action`	Required. Must match one of the `scriptActions` names declared on the step.
`features`	Optional. Attaches knowledge features to document families on the current Activity.
`nextActivity`	Optional. Requests a follow-up Activity Plan to start when the current Activity completes.

features and nextActivity are independent — return either, both, or neither.

Spawning a Follow-Up Activity

A SCRIPT step can request another Activity Plan to start automatically when the current Activity completes. Use this to chain related work, e.g. “after intake classifies an invoice, kick off the extraction plan.” The spawned Activity:

Starts only after the current Activity reaches COMPLETED (not on individual step completion).
Inherits the current Activity’s project. The target plan must already be bound to that project.
Inherits the current Activity’s document families when documentFamilyIds is omitted.
Records its source in triggerMetadata (sourceActivityId, sourceStepId, sourceActionUuid, sourceProjectId) so audit trails work in both directions.
Has triggerKind set to ACTIVITY_COMPLETED.

nextActivity shape

return {
  action: "approve",
  nextActivity: {
    activityPlanRef: "activity-plan://acme-finance/billing-extraction",
    inputs: { reviewedBy: org.userEmail, source: "intake" },
    title: "Billing for " + families[0].name,
    description: "Auto-spawned from invoice intake",
    documentFamilyIds: [families[0].id],
    features: [
      { documentFamilyId: families[0].id, featureId: "fc_billing_ready" }
    ],
    priority: 5,
    triggerMetadata: { batchId: task.data.batchId }
  }
};

Field	Required	Description
`activityPlanRef`	Yes	Slug or `activity-plan://orgSlug/planSlug` of the plan to start. Must be bound to the current project.
`inputs`	No	Object validated against the target plan’s `inputOptions` at spawn time.
`title`	No	Override the spawned Activity’s title. Defaults to the plan’s `defaultTitleTemplate`.
`description`	No	Override the description. Defaults to the plan’s `defaultDescriptionTemplate`.
`documentFamilyIds`	No	Document families to link to the spawned Activity. Defaults to inheriting the current Activity’s families.
`features`	No	Knowledge features to attach to document families before the spawn fires, so the new plan’s templates and scripts see them.
`priority`	No	Priority for the spawned Activity.
`triggerMetadata`	No	Free-form metadata. Server-controlled fields (`sourceActivityId`, etc.) always win over anything you set here.

Failure handling

Spawn failures are soft. If the target plan doesn’t exist, the plan is not bound to the current project, or inputs fail validation, the source Activity still finishes cleanly. The failure is recorded on the source step in script_result.nextActivityError. On success, script_result.nextActivityId is set to the new Activity’s ID.

Multiple spawns

Each SCRIPT step in a plan may emit its own nextActivity. They fan out at the source Activity’s completion in step insertion order. Within a single script return, only one nextActivity is supported.

Same-project only

A script can only spawn Activity Plans bound to the current project. Cross-project spawns are rejected. If you need fan-out across projects, model it through a Service Bridge call instead.

Activity SCRIPT Runtime

Activity Plan SCRIPT steps run in the server-side JavaScript runtime. The runtime exposes the same business objects the Activity is working on, plus helper namespaces for task state, document families, document content, Service Bridges, LLM calls, and knowledge features.

Object	Use
`task`	Snapshot of the Task that started the Activity, when the Activity is task-backed
`families`	Snapshot array of document families attached to the Task
`org`	Current organization `{ id, slug }`
`inputs`	The Activity’s materialized inputs object — the same values `BRIDGE_CALL` `requestBody` templates resolve against. Defaults to `{}` when the Activity has no inputs, so you can read `inputs.foo` directly without a `typeof` guard.
`tasks`	Query and mutate task records in the current project
`documents`	Query and mutate document family records in the current project
`loadDocument(familyId)` / `documents.load(familyId)`	Load a KDDB document for content nodes, tags, data objects, metadata, labels, validations, and exceptions
`lookupFeature*`	Find or create knowledge features for classification and routing
`serviceBridge`	Call project-scoped Service Bridges from custom decision logic
`llm`	Invoke configured LLM services with platform cost tracking
`log` / `console`	Write script logs visible from the Activity step details

The current Activity Plan script context is centered on the Task and its document families. The Activity’s materialized inputs are also available through the read-only inputs global, which defaults to {} when the Activity has no inputs — so you can read values such as inputs.invoiceNumber, inputs.routeId, or inputs.correlationId directly. This inputs global is a snapshot for reading and is distinct from the nextActivity.inputs spawn payload above. For prior step outputs, use declarative step mappings and pass the needed values into document metadata, task data, or downstream step configuration.

Runtime Limits

Limit	Value
Script timeout	300 seconds (5 minutes)
Document loads	5 per script execution
Task reads / document family reads	50 per namespace
Task mutations / document family mutations	20 per namespace
Task/document mutation payload	256 KB per call

The 300 second (5 minute) script timeout is the maximum wall-clock time the SCRIPT body’s JavaScript may run before it is aborted. Other step kinds use their own distinct timeouts: BRIDGE_CALL steps default to a 30 second HTTP timeout (author-overridable via the step’s timeout, capped at 120 seconds), and AI_PROMPT steps allow up to 120 seconds for the LLM call.

The script timeout and two related orchestrator budgets are operator-tunable through environment variables on the orchestrator. Authors do not set these per step; they are platform-wide defaults.

Environment variable	Bounds	Default
`PLANNER_SCRIPT_TIMEOUT`	A single `SCRIPT` step’s JavaScript execution	`300s`
`PLANNER_ADVANCE_TIMEOUT`	The detached plan-advance that runs after a step result completes (which may run further steps under one budget)	`10m`
`PLANNER_BRIDGE_CALL_TIMEOUT`	Only the `BRIDGE_CALL` request-shaping work (building the call’s body, query, path, and headers) — not the outbound HTTP call, which is governed by the step’s `timeout` above	`5s`

Plan-advance runs on its own detached budget, so a returning step-result request no longer cancels it and long SCRIPT steps are no longer stranded mid-advance. Because a SCRIPT step running inside plan-advance has its binding-side database and Service Bridge calls bounded by the advance budget, always keep PLANNER_ADVANCE_TIMEOUT greater than or equal to PLANNER_SCRIPT_TIMEOUT (the defaults preserve roughly 3x headroom). If the advance budget expires first, the script fails with context deadline exceeded before its own script timeout would fire.

Document changes are saved after the script completes. Modified KDDB documents are persisted as new content object versions with the SCRIPT_MODIFICATION transition type.

Task Namespace

Use tasks when a script needs to inspect or update human review work inside the current project.

Method	Description
`tasks.current()`	Load the current Task
`tasks.parent()`	Load the current Task’s parent, if any
`tasks.subTasks()`	List subtasks of the current Task
`tasks.subTasksOf(taskId)`	List subtasks for another Task in the same project
`tasks.get(taskId)`	Load a Task by ID
`tasks.query(filter)`	Query Tasks by `status`, `statusType`, `parentTaskId`, `templateSlug`, and `limit`
`tasks.lookupStatus(slug)`	Resolve a project Task status
`tasks.listStatuses()`	List project Task statuses
`tasks.setStatus(taskId, statusSlug)`	Change Task status and trigger Activity advancement when the status type is `DONE`
`tasks.setProperties(taskId, props)`	Merge properties into Task data
`tasks.setMetadata(taskId, metadata)`	Merge Task metadata
`tasks.setTitle(taskId, title)`	Update Task title
`tasks.setDescription(taskId, description)`	Update Task description
`tasks.lock(taskId)` / `tasks.unlock(taskId)`	Lock or unlock a Task

Document Family Namespace

Use documents when a script needs to manage document family state without loading the full KDDB document.

Method	Description
`documents.taskFamilies()`	List document families attached to the current Task
`documents.get(familyId)`	Load a document family summary
`documents.getByPath(storeSlug, path)`	Find a document family by store and path
`documents.query(filter)`	Query families by `storeSlug`, `path`, `pathContains`, `label`, `mixin`, `status`, `featureSlug`, `locked`, and `limit`
`documents.contentObjects(familyId)`	List content object versions
`documents.latestContentObject(familyId, contentType?)`	Get the latest content object, optionally `DOCUMENT` or `NATIVE`
`documents.load(familyId)`	Load the KDDB document, equivalent to `loadDocument(familyId)`
`documents.lookupStatus(slug)` / `documents.listStatuses()`	Resolve document statuses
`documents.setMetadata(familyId, metadata)`	Merge metadata into the family
`documents.addLabel(familyId, label)` / `documents.removeLabel(familyId, label)`	Manage family labels
`documents.setStatus(familyId, statusSlug)`	Update document status. For a fixed status set on step completion, prefer the step-level `setDocumentStatus` field; use this call when the status is conditional or computed
`documents.lock(familyId)` / `documents.unlock(familyId)`	Lock or unlock the family
`documents.attachToTask(familyId, taskId?)` / `documents.detachFromTask(familyId, taskId?)`	Manage Task-family links

Routing Example

This script loads the first Task document, inspects its text, and routes the Activity to review, rejection, or straight-through posting.

var family = families[0];
var doc = loadDocument(family.id);
var text = doc.getRootNode().getAllContent(" ", true).toLowerCase();

if (text.indexOf("duplicate invoice") !== -1) {
  log.warn("Duplicate invoice language detected");
  return { action: "reject" };
}

var invoice = doc.findFirstDataObjectByPath("invoice");
var amount = invoice ? Number(invoice.getFirstAttributeValue("total_amount")) : 0;

if (!amount || amount > 10000) {
  return { action: "review" };
}

return { action: "post" };

Updating Documents

Document changes made by a script are persisted after the step completes.

var family = families[0];
var doc = loadDocument(family.id);
doc.setMetadata("scriptStep", "tag-total-lines");
doc.addLabel("invoice-intake");

var root = doc.getRootNode();
var matches = root.select("//line[contains(@content, 'TOTAL')]");

for (var i = 0; i < matches.length; i++) {
  matches[i].tag("invoice/total-line", {
    confidence: 0.95,
    value: matches[i].getContent()
  });
}

return { action: "tagged" };

Do not call doc.close() in Activity Plan scripts. Kodexa persists document changes after the script completes.

Calling Service Bridges from a Script

Use serviceBridge.call() inside a SCRIPT step when the decision requires more than a single declarative bridge call.

var supplier = serviceBridge.call(
  "finance-reference-data",
  "lookup-supplier",
  { supplierId: task.data.supplierId }
);

if (!supplier || supplier.status !== "active") {
  log.warn("Supplier is not active:", task.data.supplierId);
  return { action: "review" };
}

var duplicate = serviceBridge.call(
  "finance-reference-data",
  "check-duplicate-invoice",
  {
    supplierId: task.data.supplierId,
    invoiceNumber: task.data.invoiceNumber
  }
);

return { action: duplicate && duplicate.found ? "review" : "post" };

Service bridge credentials stay in the platform. Scripts reference the configured bridge and endpoint; they do not handle secrets directly.

Shared Script Sidecars

Use scriptSidecars to pre-load reusable JavaScript helpers.

{
  "slug": "normalize-fields",
  "type": "SCRIPT",
  "scriptSidecars": ["acme-finance/invoice-script-helpers"],
  "scriptActions": [{ "slug": "normalized", "name": "normalized" }],
  "scriptBody": "normalizeInvoiceFields(families[0].id); return { action: 'normalized' };"
}

Sidecars are useful for shared validation functions, string cleanup, request mapping, and common routing decisions. Keep sidecars small and version them like any other project resource.

Design Guidance

Declare every returned action in scriptActions.
Keep scripts focused on one decision or one transformation.
Prefer BRIDGE_CALL for a single external API call that operators should see as its own step.
Use logs at important decision points.
Make scripts idempotent when they can be retried.
Avoid long loops and repeated document loads.

Next Steps

Script API Reference

See the full JavaScript context, document helpers, LLM calls, and logging reference.

Service Bridge Steps

Learn when to model an external API call as its own Activity Plan step.

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

When to Use a SCRIPT Step

Step Configuration

Return Value

Spawning a Follow-Up Activity

nextActivity shape

Failure handling

Multiple spawns

Same-project only

Activity SCRIPT Runtime

Runtime Limits

Task Namespace

Document Family Namespace

Routing Example

Updating Documents

Calling Service Bridges from a Script

Shared Script Sidecars

Design Guidance

Next Steps

Script API Reference

Service Bridge Steps

​When to Use a SCRIPT Step

​Step Configuration

​Return Value

​Spawning a Follow-Up Activity

​nextActivity shape

​Failure handling

​Multiple spawns

​Same-project only

​Activity SCRIPT Runtime

​Runtime Limits

​Task Namespace

​Document Family Namespace

​Routing Example

​Updating Documents

​Calling Service Bridges from a Script

​Shared Script Sidecars

​Design Guidance

​Next Steps

Script API Reference

Service Bridge Steps

When to Use a SCRIPT Step

Step Configuration

Return Value

Spawning a Follow-Up Activity

nextActivity shape

Failure handling

Multiple spawns

Same-project only

Activity SCRIPT Runtime

Runtime Limits

Task Namespace

Document Family Namespace

Routing Example

Updating Documents

Calling Service Bridges from a Script

Shared Script Sidecars

Design Guidance

Next Steps