Process script API

Script steps run finite Node.js programs inside a selected sandbox. Use @ailaflow/bridge-lib to access process state and AilaFlow resources.

Runtime

• The entry point is main.js.
• Define npm dependencies in package.json; AilaFlow installs them with pnpm.
• Additional JavaScript files are supported.
• A script must finish. Do not start a long-running service.
• Leave fatal errors uncaught so the Process Tester receives stderr and the stack trace.

Import the API:

const ailaflow = require('@ailaflow/bridge-lib');

Prefixes are optional: $name and name, #customers and customers, or /process and process are equivalent in this API.

Variables

readVariable(name)

Returns the variable value or null when unset. Fails if the variable does not exist.

const request = await ailaflow.readVariable('$request');

writeVariable(name, value)

Writes a value to a selected variable. The value must match its JSON Schema.

await ailaflow.writeVariable('$status', 'completed');

Processes

executeProcess(name, startValues, rpcConfig?)

Executes an allowed process and waits for its result:

const output = await ailaflow.executeProcess(
  '/summarize',
  { text: 'Summarize this text.' },
  { timeout: 30_000 }
);

Requirements:

• The process must be allowed by the Script step.
• The current user must have access to it.
• startValues must contain all and only its start variables.
• A pausable process can start, but the call fails if execution pauses.
• The default RPC timeout is 10 seconds.

Tables

Tables are created dynamically. Reads tolerate missing tables and columns. Writes establish and preserve column types.

readTableRow(table, id)

Returns a row with _id and _updatedAt, or null when it does not exist:

const customer = await ailaflow.readTableRow('#customers', 'customer_1');

readTablePage(table, options?)

Returns { rows, page, pageSize, hasMore }.

const page = await ailaflow.readTablePage('#customers', {
  page: 1,
  pageSize: 100,
  orderBy: 'amount_minor',
  ascending: true,
  where: {
    status: { $eq: 'active' },
    amount_minor: { $gte: 1000, $lt: 10000 }
  }
});

Defaults: page 1, page size 100, order by _id, ascending.

Filters support $eq, $neq, $lt, $gt, $lte, and $gte with string, number, or boolean values. Conditions use AND. JSON columns cannot be filtered or ordered.

A missing table, filter column, or ordering column returns an empty page.

writeTableRow(table, row)

Creates or replaces a row. _id is required and must be a string.

await ailaflow.writeTableRow('#customers', {
  _id: 'customer_1',
  status: 'active',
  amount_minor: 2500
});

AilaFlow generates _updatedAt. Do not use other top-level names beginning with _. Top-level null values are not supported. Objects and arrays are stored as JSON.

deleteTableRow(table, id)

Returns true when a row was deleted and false when the table or row did not exist.

const deleted = await ailaflow.deleteTableRow('#customers', 'customer_1');

Secrets

encryptSecret(secret)

Encrypt passwords, tokens, and other secrets before storing them in a table:

const encrypted = await ailaflow.encryptSecret(apiToken);

decryptSecret(encryptedSecret)

Decrypts a value created by encryptSecret.

const apiToken = await ailaflow.decryptSecret(row.encryptedToken);

Never log, return, or persist decrypted plaintext. Encryption does not protect plaintext previously stored in a variable or task submission.

Utilities

Convert resolved users into an expression when needed:

const expression = (await ailaflow.resolveProcessUserAccess()).join(' or ');

RPC configuration

Async bridge functions accept an optional final RPC configuration:

await ailaflow.readVariable('$large_input', { timeout: 30_000 });

RPC failures reject the call. Catch only errors you can handle; rethrow fatal errors.