Writing and testing a script Preview

Creating one

In the Connector's own console: Automation, then Scripts, then New script.

Field	Notes
Name	How you will pick it when creating an event handler. Readable by ScriptName()
Description	For your own benefit; scripts cannot read it
Code	The script itself
Enabled	A disabled script never runs, even where a handler names it

Validate compiles the source and reports any parse error. It does not run anything, so it catches a missing brace and nothing else. A script that does not parse is refused on save.

Saving applies to the next matching operation. No restart, no reconnect. The Connector keeps the handler table in memory and rebuilds it on every save.

Binding it

A script does nothing until an event handler names it. One script can be bound by many handlers, at different priorities, on different events, scoped to different virtual file systems. The script is the code; the handler carries every execution decision: which event, what timeout, what happens on failure, whether it runs in the background.

Getting it into production safely

The failure mode that hurts is a before handler that refuses transfers because of a typo. The order below is designed so that cannot happen to you.

1. Write the script and Validate it. Syntax only, but free.
2. Bind it to one virtual file system, never to Everything, while you are working on it.
3. Set the fail mode to Let the operation proceed. A broken script then logs and steps aside instead of blocking real work. See Fail mode.
4. Log generously. Log.Info(JSON.stringify(EventCtx())) at the top of a new script tells you exactly what the engine handed it.
5. Trigger it for real and watch Activity and the Connector log.
6. Tighten last: widen the scope, then set the fail mode back to Block the operation.

A one line script is a good first script

Bind Log.Info("fired: " + JSON.stringify(EventCtx())); to the event you care about and trigger it once. You will learn more from that single line than from reading any page on this site, because it prints the exact context your real script will receive.

Timeouts

Every execution is time bounded. The event handler sets the timeout in milliseconds; when it is left at zero the default is 5000 ms.

When the deadline passes the engine interrupts the script wherever it is. The handler's result is a timeout error, which on a fail closed before handler refuses the operation.

Two functions let a script see its own budget:

Log.Info("this handler allows " + ExecutionTimeout() + " seconds");

// ExecutionTimeLeft() is a duration. Divide by 1e9 for seconds, or call .Seconds().
if (ExecutionTimeLeft() / 1e9 < 2) {
    Log.Warn("not enough time left for the optional step, skipping it");
    Exit(0);
}

ExecutionTimeout() reports whole seconds, so a 2500 ms handler reports 2. Use it as a rough budget, not as a precise deadline.

A before script sits on the data path

A before handler runs while the user's client waits. Every millisecond it spends is a millisecond added to their upload. Anything that calls out to a slow service belongs on an after handler marked Run in the background, not in front of a transfer.

Deleting a script

A script in use shows how many handlers reference it. Deleting it leaves those handlers pointing at nothing, and a handler whose script is missing is simply inert: it never runs and never blocks anything. Delete or repoint the handlers too, so the console stops showing you a lie.

What the engine does not give you

The engine is not Node.js and not a browser. There is no console, no fetch, no window, no process, no file descriptor API and no npm. The equivalents are all in the standard library: Log() instead of console.log, HttpCli instead of fetch, local file functions instead of fs.

Full detail on the dialect, including what parts of JavaScript itself are available: The JavaScript dialect.