Script

Manual / Actions / HTTP and scripting

Transform workflow data and call an approved API.

Read Shared action rules for disabling this action, outputs, error routing, and recovery.

Configuration and behavior

Script runs restricted ES2022 JavaScript once per item and returns one value as ${steps.<slug>.result}. It can call an HTTP API through a named saved connection. It cannot read or write files, start processes, load packages, read environment variables, or reach the Relay host.

Service address. For Basic and token connections, enter the scheme, host, and optional port, such as https://api.example.com. Relay refuses a path other than /, user information, query text, or a fragment. Add the API path in the request source. Iconik uses its saved Base URL, including the /API path.

Writing the script. The source editor sits in the node bench. Expand editor to the full window gives the same editor more room, with the same Test controls and selected-step result. Source is a synchronous function body: return a direct value, a promise, or a returned async IIFE. Do not use bare top-level await.

The full-window Script editor keeps workflow testing and step results in view.

What a script can use. input is read-only workflow data under trigger, item, run, node, steps, vars, and error. Inside a For Each repeated path, the current item is also available as input.loop.item. It keeps its JSON type and changes for each iteration. input.loop.item is absent outside that repeated path and after Done. A missing path is undefined; input.get(path, fallback) states a fallback. A protected path still fails. connections supplies public fields and protected credential handles. http has request plus get, post, put, patch, delete, head, and options. response.text() and response.json() read the already buffered response synchronously.

Use protected handles only in request authentication, headers, or JSON leaves. For Basic authentication use auth.basic with username and password, for a token use auth.bearer, and for another scheme use auth.scheme with auth.credentials. Iconik uses separate App-ID and Auth-Token headers. The request, including redirects, must stay on the connection's scheme, host, and port. Relay follows at most 10 redirects. Logging or converting a protected handle shows [protected connection value]; returning it is refused.

Date, Math.random, timers, TextEncoder, and UTF-8 TextDecoder are available. TextDecoder does not stream. Intl, modules, packages, files, processes, and environment variables are unavailable. date formats explicit times, path performs portable text-only path operations, and console writes recorded diagnostics.

What a script may return. null, a boolean, text, a finite safe number, a dense list, or an ordinary string-keyed object. Functions, proxies, getters, altered prototypes, sparse lists, cycles, undefined, BigInt, NaN, and infinities are refused. A repeated ordinary object is copied independently in each result position. A returned promise must settle inside the timeout.

Limits per item. Source is limited to 256 KiB; input and result to 10 MiB; JavaScript heap to 128 MiB; process memory to 256 MiB; all Script workers on a node to 1 GiB; and console output to 256 KiB. Relay can run four workers but reserves one for editor checks, so at most three live Scripts run together.

A Script can have at most four pending HTTP requests. Their reserved response limits must total at most 32 MiB, so the default setting allows three and the maximum setting allows one. Pending request data has a separate 10 MiB combined limit. An excess request is refused before sending with error.kind set to request. Await an earlier request before starting another. Completed responses count against the JavaScript heap and can be collected when no longer used.

Failures. The Error exit distinguishes script, input, result, timeout, cancellation, memory, stack, pending_job, result_size, diagnostic_size, admission, and abnormal. Only a successful run publishes a result.

Testing a script. Script uses the workflow's Test and Replay controls (4.6). There is no separate Script runner. Test and Replay make real requests and can change external data. Cancellation cannot undo a request already sent, and Relay does not retry requests automatically. See Use Script API connections and Workflow Test runs.

Recorded evidence. Ordinary Script results, console lines, and downstream values remain available even when API or upstream data contains a token-like value. Relay still removes stored credential values and applies its existing evidence masking when it records and serves Test evidence. Keep secrets out of source and console output. Relay cannot reliably identify an unknown, partial, or transformed secret, so review external data before retaining or sharing it.

Source screening. Relay scans Script source for credential-looking literals before save, evaluation, import, or transfer. A blocked credential-like literal must be removed. An ambiguous literal needs acknowledgement. Screening does not rewrite the source stored on the node and does not compare source to stored credential values.

The author's guide is Script authoring guide.