a9script

Docs / Reference

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.

This is one part of the authoring pack — how a script is executed at all is the model part, and the other groups of functions are parts of their own. All of them are named at the end.

Generated — do not edit. Every block of script below is executed by the platform’s own test suite, and every error message is the one the platform produces today, so none of this can be what was true when someone last wrote it down.

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.
  • data (object, optional) — Structured payload kept with the line, for detail a sentence cannot carry.

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.

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).

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.

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.

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.

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);

The rest of this pack

The page above is everything that is true only HERE. Ask for these parts by name for the rest:

  • model — how a script is executed, the shape of its input, the rules enforced while it runs, and the mistakes that do not work here.
  • functions-encoding — the encoding functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-crypto — the crypto functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-text — the text functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-number — the numbers functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-structured — the structured data functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-document — the documents functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-markdown — the markdown functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-datetime — the date & time functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-email — the email functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-blob — the files functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-mapping — the mapping functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-dataset — the datasets functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-state — the state functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-pagination — the pagination functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-control — the run control functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • functions-functions — the config functions — what each one does, its arguments, whether it pauses the run, and a line of real script.
  • mistakes — the habits from general JS that do not work here — each with the exact error it produces and the shape to write instead.
  • standard-library — every built-in the language itself provides — JSON, Math, Object, String, Array, Number, Map, Set, Date, RegExp and the bare globals — one line each, with an example and its answer.
Rendered from docs/guide/authoring-pack-functions-core.md in the product's own repository, at build time. Found a problem on this page? Write to the address in the footer.