Syncplify.me Server v8

Appearance

Breaking changes from previous Syncplify Server!' versions ​

This page outlines the significant changes ("breaking changes") introduced in the latest version of the software, as compared to previous versions. It also provides guidance on how to smoothly adapt to these changes when upgrading to the version described in the current documentation.

GetCurrentVFS() is no longer a member of the Session object ​

In previous versions of Syncplify Server!, to work with the currently active Virtual File System (VFS) from inside a SyncJS script, you'd call:

ts
var currVfs = Session.GetCurrentVFS();
if (currVfs != null) {
    // do something with it
}

In Syncplify Server!, GetCurrentVFS() has become a stand-alone function, and is no longer a member of the Session object. You will then need to update all of your scripts using this method, in order to call it like this:

ts
var currVfs = GetCurrentVFS();
if (currVfs != null) {
    // do something with it
}

Read more about this method here.

VFS' ImportFile() and ExportFile() function signature differences ​

In previous versions of Syncplify Server! the ImportFile() and ExportFile() methods of a VFS object would take a file path and a directory path as arguments, which lead to all kinds of confusion. These functions signatures have now been uniformed as follows:

ts
function ImportFile(localFilePath, targetVfsFilePath: string) respBase;
function ExportFile(vfsFilePath, localFilePath: string) respBase;

Read more on this topic on the specific manual pages for ImportFile and ExportFile.

CtxRelPath() replaces Session.GetRelPath() / Session.GetAbsPath() in event-handler scripts ​

In Syncplify Server! versions 1 through 6, the only way to retrieve the path of the file associated with a triggered event from inside a script was to call Session.GetRelPath() or Session.GetAbsPath(). This was always subtly unreliable: those methods return the session's live path cursor, which may have already changed by the time the script executes — because the client keeps working concurrently.

Syncplify Server! V7 (and thus also V8 and all subsequent versions) introduced the dedicated CtxRelPath() helper function. The path is captured at the moment the event fires and frozen into the script's execution context for its entire lifetime, regardless of what the client does afterwards.

If you have existing scripts that call Session.GetRelPath() or Session.GetAbsPath() in order to determine which file triggered a file-based event, you should update them to use CtxRelPath() instead:

ts
// Before (V1–V6) — unreliable under concurrent session activity:
var path = Session.GetRelPath();

// After (V7+) — always correct:
var path = CtxRelPath();

NOTE

Session.GetRelPath() and Session.GetAbsPath() still exist and are still valid for their original purpose (inspecting the session's current cursor position). Only use them when you genuinely need that live cursor, not when you need the file that triggered the script.

CtxRelTargetPath() replaces Session.GetRelTargetPath() in event-handler scripts as of v8.0.2 ​

This one is far more specific than CtxRelPath(): it gives you the path of the target file before and after a Move/Rename operation. The logic is the same as for CtxRelPath(): the path is captured at the moment the event fires and frozen into the script's execution context for its entire lifetime, regardless of what the client does afterwards.

ts
// Before v8.0.2 — unreliable under concurrent session activity:
var targetPath = Session.GetRelTargetPath();

// After v8.0.2 — always correct:
var targetPath = CtxRelTargetPath();

WARNING

CtxRelTargetPath() is not available prior to v8.0.2. Please upgrade to v8.0.2 or newer to use this function.

CtxVFSName() replaces Session.GetCurrentVFSName() in event-handler scripts as of v8.0.4 ​

This function provides the name of the virtual file system (VFS) associated with the current event. As with the other Ctx* functions, the VFS name is captured at the moment the event fires and frozen into the script's execution context for its entire lifetime, ensuring consistent behavior even under concurrent session activity.

ts
// Before v8.0.4 — unreliable under concurrent session activity:
var vfsName = Session.GetCurrentVFSName();

// After v8.0.4 — always correct:
var vfsName = CtxVFSName();

Read more about this function here.

WARNING

CtxVFSName() is not available prior to v8.0.4. Please upgrade to v8.0.4 or newer to use this function.

New EventCtx() helper function as of v8.0.4 ​

Alongside CtxVFSName(), v8.0.4 also introduces the EventCtx() helper function. It returns the whole event context as a single object, carrying the same frozen values the individual Ctx* functions expose:

ts
var ctx = EventCtx();
Log("File path: " + ctx.RelPath);         // same as CtxRelPath()
Log("Target path: " + ctx.RelTargetPath); // same as CtxRelTargetPath()
Log("VFS name: " + ctx.VFSName);          // same as CtxVFSName()

This is not a breaking change, existing scripts keep working unmodified. It is worth knowing about because EventCtx() is forward compatible: when future versions enrich the event context with new information, the new fields appear in this object automatically, without waiting for a dedicated Ctx* function.

WARNING

EventCtx() is not available prior to v8.0.4. Please upgrade to v8.0.4 or newer to use this function.

New CtxUsername() helper function as of v8.0.5 ​

v8.0.5 introduces the CtxUsername() helper function, which works exactly like the other Ctx* functions: it returns the username of the user who logged in and started the session that triggered the script, captured at the moment the event fires and frozen into the script's execution context for its entire lifetime. It returns an empty string "" for events that occur before authentication.

ts
var user = CtxUsername();
if (user !== "") {
    Log("Event triggered by user: " + user);
}

As promised by the forward compatibility of EventCtx(), the same value is also available as the new Username field of the event context object, with no changes needed in scripts that already read it:

ts
var ctx = EventCtx();
Log("File path: " + ctx.RelPath);         // same as CtxRelPath()
Log("Target path: " + ctx.RelTargetPath); // same as CtxRelTargetPath()
Log("VFS name: " + ctx.VFSName);          // same as CtxVFSName()
Log("Username: " + ctx.Username);         // same as CtxUsername(), new in v8.0.5

This is not a breaking change, existing scripts keep working unmodified.

WARNING

CtxUsername(), and the Username field of EventCtx(), are not available prior to v8.0.5. Please upgrade to v8.0.5 or newer to use them.

New CtxVirtualSite() helper function as of v8.0.6 ​

v8.0.6 introduces the CtxVirtualSite() helper function, which returns the ID of the virtual site in whose context the event occurred, captured at the moment the event fires and frozen into the script's execution context for its entire lifetime. Unlike the other Ctx* functions, it never returns an empty string: every worker instance serves exactly one virtual site and will not start without one, so there is no event that fires outside a virtual site.

ts
Log("Event fired in virtual site: " + CtxVirtualSite());

The same value is also available as the new VirtualSite field of the EventCtx() object:

ts
var ctx = EventCtx();
Log("Username: " + ctx.Username);         // same as CtxUsername()
Log("Virtual site: " + ctx.VirtualSite);  // same as CtxVirtualSite(), new in v8.0.6

This is not a breaking change, existing scripts keep working unmodified. Session.GetVirtualSite() returns the same value and is not deprecated: unlike the session's file cursor or current VFS, the virtual site cannot change during a session, so neither call can go stale.

WARNING

CtxVirtualSite(), and the VirtualSite field of EventCtx(), are not available prior to v8.0.6. Please upgrade to v8.0.6 or newer to use them.