Breaking changes from Syncplify AFT! v3 to v4

This page lists every change in Syncplify AFT! v4 that requires a script or a configuration to be updated before it runs as expected. Read it before upgrading any production instance.

The short answer for most users: the vast majority of v3 scripts run in v4 without any modification. The only scripts that need changes are those that use one of the features listed below.

INFO

Syncplify AFT! v3 is retired, and every recipe in this section is written for v4. The migration command aft import-from-aft3 brings scripts, named secrets, API keys and cron jobs over from a v3 installation; its --from flag points at the v3 configuration directory when it is not in the default location. The two things it does not carry over are explained at the end of this page.

FsWatcher.Start() now requires a callback

The v3 pattern no longer works:

watcher.Start();

while (true) {
    Sleep(500);
    if (HaltSignalReceived()) {
        break;
    }
    var evt = watcher.Events();
    for (var i = 0; i < evt.length; i++) {
        if (evt[i].Event == 'WRITE') {
            doSomethingWith(evt[i].Object);
        }
    }
}

The v4 pattern:

watcher.Start(function(evt) {
    // evt = { TimeStamp, Event, Object }
    if (evt.Event == EVT_WRITE) {
        doSomethingWith(evt.Object);
    }
});

WaitForHaltSignal();
watcher.Stop();

What changed:

• Start() requires a callback function as its only argument. Called without one, it silently does nothing.
• Events() has been removed. There is no queue to poll any more.
• WaitForHaltSignal() replaces the while, Sleep and HaltSignalReceived loop. It blocks until a halt signal arrives, using no CPU and producing no log noise.
• Stop() is a new, required step after WaitForHaltSignal() returns. It waits until the internal event loop has fully exited before returning, so no further callback fires once the script continues past that point.

Event types: in v3 the event types were uppercase strings ("WRITE", "CREATE", "REMOVE", "RENAME", "CHMOD"). In v4 they are named constants (EVT_WRITE, EVT_CREATE, EVT_REMOVE, EVT_RENAME, EVT_CHMOD). Update every comparison accordingly. See Uploading local folder changes to SFTP in real time for complete v4 watcher scripts.

The RemoteWatcher constructor now takes a VFS name

The v3 pattern no longer works:

var rcli = new SftpClient();
rcli.Host  = 'files.example.com:22';
rcli.User  = 'uploader';
rcli.Pass  = 's3cr3t';
rcli.Connect();

var rw = new RemoteWatcher(rcli);

The v4 pattern:

// "production-sftp" is the name of an entry in the AFT! VFS library
var rw = new RemoteWatcher("production-sftp");

What changed: the constructor no longer accepts a live client object. It takes a string, the name of a connection profile stored in the virtual file systems library. The engine resolves the profile, decrypts its credentials and opens the connection internally. Credentials never appear in script source in v4.

To migrate: create a virtual file system entry for each remote system your RemoteWatcher scripts target, then replace the client construction code with new RemoteWatcher("profile-name"). The complete v4 script is in Downloading new remote files as they arrive.

HaltSignalReceived is a function only

In v3 the name could be referenced as a property, a deprecated form kept for compatibility with even older scripts. In v4 it is a function, and only a function.

The v3 form that no longer works:

if (HaltSignalReceived) {   // property access, no parentheses
    break;
}

The v4 form:

if (HaltSignalReceived()) {   // function call, parentheses required
    break;
}

Why this matters: a bare reference to a function, without calling it, is always truthy in JavaScript, regardless of the actual halt state. A script that writes if (HaltSignalReceived) without parentheses evaluates the condition as true on the very first iteration and exits immediately, never processing any event.

Most scripts that reach v4 with FsWatcher or RemoteWatcher will be rewritten to the callback pattern and WaitForHaltSignal() anyway, at which point this function is rarely needed. It remains available for scripts that prefer explicit polling.

The *FromSecret credential properties have been removed

In v3, every client object exposed shortcut properties that accepted a secret name and resolved it internally. These properties no longer exist in v4.

The v3 pattern that no longer works:

var sftpcli = new SftpClient();
sftpcli.User           = 'uploader';
sftpcli.PassFromSecret = 'name-of-my-secret';       // v3 shortcut property

var s3cli = new S3Client();
s3cli.APIKeySecretFromSecret = 'aws-secret-name';   // v3 S3 shortcut property

cli.Options.OTFEKeyFromSecret = 'otfe-key-secret';  // v3 OTFE shortcut property

The v4 pattern:

var sftpcli = new SftpClient();
sftpcli.User = 'uploader';
sftpcli.Pass = GetSecret('name-of-my-secret');      // call GetSecret() inline

var s3cli = new S3Client();
s3cli.AccessKey = GetSecret('aws-access-key');      // the v4 S3 credential fields
s3cli.SecretKey = GetSecret('aws-secret-name');     // are AccessKey and SecretKey

cli.Options.OTFEKey = GetSecret('otfe-key-secret'); // OTFEKey is the v4 field name

What changed: the *FromSecret shortcut properties (PassFromSecret, APIKeySecretFromSecret, Options.OTFEKeyFromSecret and any other of the same pattern) are gone. In v4, GetSecret("name") is a first class global function. Call it directly and assign its return value to the credential field.

Migration: search all script files for the string FromSecret. Each occurrence maps mechanically to a GetSecret() call: replace client.XFromSecret = "name" with client.X = GetSecret("name"), substituting the base field name (Pass, SecretKey, OTFEKey and so on).

Admin accounts are not migrated

AFT! v3 stored admin passwords as SHA-256 hashes of a random salt, the user name and the password. AFT! v4 uses bcrypt, an incompatible format. Because the plain text passwords cannot be recovered from the v3 hashes, migrating admin accounts would only produce accounts nobody could log into.

aft import-from-aft3 therefore imports no admin profile. AFT! v4 creates the initial admin account during the first run setup, and any additional admin account is recreated by hand in the v4 web UI after that.

The Blockly script type is removed

AFT! v3 allowed scripts to be authored in Blockly, a visual, block based editor. AFT! v4 supports SyncJS JavaScript scripts only. Blockly scripts are skipped during the migration, with a warning that lists each one by name; they cannot run in v4.

If any Blockly script is still in use, its logic must be rewritten in JavaScript after the upgrade.