Scripts Preview

A script is reusable JavaScript, run by the Connector's embedded SyncJS engine when an event handler binds it to a file event.

Scripts run on your Connector, on your hardware, next to your files. Nothing about them travels to SFTP.cloud.

This page is the console. The language has its own book

Everything here is about creating, binding and deleting a script in the Connector's admin console. The language itself, every function it defines and every difference from the same language in Syncplify Server, is documented in Scripting.

Creating one

Automation, then Scripts, then New script.

Field	Notes
Name	How you will pick it when creating an event handler
Description	For your own benefit
Code	The script itself
Enabled	A disabled script never runs, even where a handler names it

Validate checks the syntax without running anything. A script that does not parse is refused.

Saving applies to the next matching operation. No restart.

What a script can see

The event context is available through these globals:

Call	Returns
CtxRelPath()	The path the operation is about
CtxRelTargetPath()	The destination path, on a rename or move
CtxUsername()	The user who triggered it
CtxVFSName()	The virtual file system it happened in
EventHandler()	The event id, for example before.upload
HandlerPriority()	This handler's priority
EventCtx()	The whole context as one object

The Session object carries the same facts in the shape Syncplify Server scripts use, so scripts stay portable between products:

Session.GetRelPath()
Session.GetRelTargetPath()
Session.GetUserID()
Session.GetID()
Session.GetCurrentVFSName()

Methods that have no meaning on a Connector, such as Session.GetRemoteAddress(), throw a descriptive error rather than returning something misleading. Full detail: The event context.

GetCurrentVFS() returns the live virtual file system of the event, so a script can read and write your storage, encryption at rest included.

GetCurrentVFS() is not limited to what the user can reach

It has full access to that entire virtual file system and does not apply the triggering user's permissions. Permissions are checked before your script runs, for the operation that triggered it; everything the script does afterwards is unchecked. See The virtual file system object.

What a script can do

The engine ships a large standard library: logging, HTTP requests, SQL against eight database engines, archives, path utilities, encoding and hashing, virtual file system access, remote SFTP, FTPS, S3, Azure and Google Cloud clients, AMQP, PGP and image processing.

Log.Info("uploaded " + CtxRelPath() + " by " + CtxUsername());

The complete list is Every global, A to Z.

Three things need configuring before they work

GetSecret() reads the secret store, and SendMail() and NotifyViaTelegramBot() send through the SMTP and Telegram tabs of Settings. Until those are filled in, the first returns an empty string and the other two return false.

None of the three raises an error, so a script that relies on one and does not check the return value fails silently. The reason is always in the log; see If you know Syncplify Server.

Blocking an operation

A script bound to a before event is a policy gate. To refuse the operation, stop with a non zero exit:

// Refuse uploads of executables.
var name = CtxRelPath().toLowerCase();
if (name.endsWith(".exe") || name.endsWith(".dll")) {
    Log.Warn("refused executable upload: " + CtxRelPath());
    Exit(1);
}

Exit() or Exit(0) stops the script cleanly and lets the operation proceed. Any non zero code refuses it.

A script that throws, or that times out, is treated the same way as a refusal by default. See Event handlers for the fail mode setting.

Timeouts

Every execution is time bounded. The event handler sets the timeout; when it does not, the default is 5 seconds.

A script sits on the data path

A before script runs while the user waits. Keep it short. Anything that calls out to a slow service belongs on an after handler marked to run in the background, not in front of an upload.

Where output goes

Log(), and its Log.Trace, Log.Debug, Log.Info, Log.Warn and Log.Error methods, write to the Connector's own log. See Settings for where that log is written.

The severity methods are named Warn and Error. There is no Log.Wrn or Log.Err; calling one stops the script.

Writing and testing safely

1. Write the script and Validate it.
2. Bind it to an event handler scoped to one virtual file system, not everything.
3. On a before handler, set the fail mode to Let the operation proceed while you are testing, so a mistake does not stop real transfers.
4. Watch Activity and the Connector log.
5. Widen the scope and tighten the fail mode once it behaves.

Longer version, with the reasoning: Writing and testing a script.

Deleting one

A script in use by handlers shows how many. Deleting it leaves those handlers pointing at nothing; delete or repoint the handlers too.

Where to go next

You want	Read
The language, start to finish	SyncJS on the Connector
Which events exist and what each carries	Events and when they fire
Complete scripts you can adapt	Worked examples
To port a script from Syncplify Server	If you know Syncplify Server