Docs / Language & functions

a9script authoring pack — core functions

The core functions, with their arguments and a line of real script each. Called by bare name; nothing is imported. A call marked pauses does real work outside the script: the run is saved, and continues on the next line with the result.

log(message, data?) — pauses

Writes an info line to the run’s log — the record an operator reads afterwards.

• message (string) — The line’s text. A non-string value is recorded as JSON, shown as for data.
• data (object, optional) — Structured payload kept with the line, for detail a sentence cannot carry. A Map in it shows as its [key, value] pairs, a Set as its values, a RegExp as its text (/x/g) and an Error as its name and message plus its own fields, then its cause shown the same way; an error that causes itself ends the chain there. Every other platform function refuses a Map, a Set or a RegExp.

Answers: Nothing.

log("order received", { id: input.event.body.id });

logInfo(message, data?) — pauses

Writes an info line — the explicit spelling of log.

• message (string) — The line’s text.
• data (object, optional) — Structured payload kept with the line. Maps, Sets, RegExps and Errors show as log shows them.

Answers: Nothing.

logInfo("sync finished", { contacts: 42 });

logError(message, data?) — pauses

Writes an error line. The run continues — an error line reports, it does not end anything; throw or return to end a run. A triggered run that logs one also turns its script’s health red until somebody acknowledges it; a Test never does.

• message (string) — What went wrong.
• data (object, optional) — Structured payload kept with the line (the offending record, a status). Maps, Sets, RegExps and Errors show as log shows them.

Answers: Nothing.

logError("contact rejected by the CRM", { id: input.event.body.id, status: 422 });

logWarning(message, data?) — pauses

Writes a warn line — something survivable that a human should still see. A triggered run that logs one turns its script’s health amber until somebody acknowledges it; a Test never does.

• message (string) — What is off.
• data (object, optional) — Structured payload kept with the line. Maps, Sets, RegExps and Errors show as log shows them.

Answers: Nothing.

logWarning("contact has no address — skipped", { id: input.event.body.id });

logVerbose(message, data?) — pauses

Writes a verbose line. Kept in full while the run is recent; dropped from a SUCCEEDED run’s archived copy, so detail is cheap here.

• message (string) — The detail line.
• data (object, optional) — Structured payload kept with the line. Maps, Sets, RegExps and Errors show as log shows them.

Answers: Nothing.

logVerbose("page fetched", { page: 3, items: 25 });

logDebug(message, data?) — pauses

Writes a debug line. Like logVerbose, it is dropped from a succeeded run’s archived copy and kept in full on a failed one.

• message (string) — The debug line.
• data (object, optional) — Structured payload kept with the line. Maps, Sets, RegExps and Errors show as log shows them.

Answers: Nothing.

logDebug("mapping the trigger payload", { raw: input.event.body });

respond(value) — pauses

Answers the caller of a synchronous API call with value, as JSON. At most once per run — a second call throws. The run keeps going after it, and a run triggered by anything else (webhook, schedule, mail) simply has nobody listening.

• value (any) — The JSON-serialisable answer. respond(undefined) is a real, empty answer.

Answers: Nothing.

respond({ ok: true, received: input.event.id });

stop() — pauses

Does nothing — kept so the name resolves. A run ends with a top-level return (whose value becomes the run’s output) or by throwing.

Answers: Nothing.

stop(); // does not end the run
return "nothing to do";

echo(value) — pauses

Sends a value to the platform and back — a diagnostic. It answers identically in an on-demand Test run and in a dispatched one, which is what makes it useful when a script’s surroundings are in doubt. It carries no business meaning.

• value (any) — Any JSON-serialisable value; the same value comes back.

Answers: The value it was given.

const pong = echo("ping");
log("round trip: " + pong);

fetch(request) — pauses

Calls a configured HTTP connection. Authentication, retries, throttling, token refresh and log redaction are the platform’s job — the script names a connection and a path. A non-2xx answer RETURNS (branch on status); a call that could not be made throws, catchable, with its code in the message.

• request (object) — { connection, method, path | url, query?, headers?, body?, timeoutMs? }. connection is the name of a configured HTTP connection; path is joined onto its base URL. Any other field is refused by name — the platform binds the tenant and environment itself.

Answers: { status, headers, body } — header names lowercased, body parsed when it is JSON.

const response = fetch({
  connection: "crm",
  method: "GET",
  path: "/contacts",
  query: { updatedSince: input.settings.since }
});
if (response.status !== 200) {
  throw new Error("crm answered " + response.status);
}
log("contacts: " + response.body.items.length);

input — read, not called

The run’s input — a global variable filled from OUTSIDE before the script starts: input.event is what triggered the run, input.settings is what the linked settings script returned. Read-only: the whole object is frozen, and assigning to it throws.

Holds: { event, settings }.

log("triggered by " + input.event.kind);

input.event — read, not called

What started this run: the webhook or API call, the scheduled fire, the arrived mail. Read-only — the whole input is frozen, and assigning to it throws.

Holds: { kind, id, endpoint?, body, headers?, receivedAt, tenantId, environmentId } — body is the caller’s payload, kind says which door it came through.

const order = input.event.body;
log("order " + order.id + " via " + input.event.kind);

input.settings — read, not called

The value the linked settings script returned, evaluated once before this run started — configuration as data, so environment-specific values never sit in the script. undefined when no settings script is linked.

Holds: Whatever the settings script returned.

const baseUrl = input.settings.crmBaseUrl;
log("using " + baseUrl);