Snapshots

Documentation home

Introduction. 1

Durability of snapshots 1

Snapshot Manager 1

Create a snapshot 1

Search snapshots 2

Restore a snapshot 2

Delete a snapshot 2

Example (Javascript) 2

See also: Javadoc for SnapshotManager, Snapshot, SnapshotQuery

Introduction

A snapshot contains the state of a user’s form at a given moment, and this can be saved and then restored at some future point. The ability to create, restore and search snapshots is provided by the Snapshot Manager and this can be accessed using an API based scripting language e.g. Javascript. This enables an application to provide the user with the ability to interrupt their work e.g. filling in a tax form, and then return to it later. This feature is not available using the FPL language.

Each snapshot contains the state of the user’s current form plus any forms in the “stack” i.e. all calling forms.

This ability to create and restore a snapshot under program control represents a more flexible alternative to the Save/Restore feature.

Durability of snapshots

Ebase does not guarantee that a snapshot created in one release can be restored in a different release, although in most cases it is anticipated that this should work without problem. There is a known issue that it is not possible to restore snapshots created in Ebase V4.4.3 or earlier releases using Ebase version 4.4.4 or above.

Snapshot Manager

The Snapshot Manager provides the ability to:

• Create a snapshot
• Search snapshots
• Restore snapshots
• Delete snapshots

Create a snapshot

This is done using Api method SnapshotManager.createSnapshot(). See SnapshotManager javadoc.

String system.snapshotManager.createSnapshot(fields, expiryDate);

Where fields is a list of key/value pairs that provide additional information about the snapshot. When saving a user’s work, this would commonly contain some sort of application identifier e.g. the form id, and some sort of user identifier e.g. the user id or an email address. But it can also contain any additional information e.g. it might also contain security data such as a password, security questions etc. These key/value pairs can be used when searching snapshots.

Each snapshot is saved in the system’s internal database and contains the following:

• The state of the user application including the current form and any calling forms in the form stack
• A unique snapshot id – this is system generated and cannot be changed
• The snapshot creation date
• An optional snapshot expiry date
• Any number of key/value pairs as described above

Search snapshots

Snapshots can be searched with Api method SnapshotManager.getSnapshots() using a SnapshotQuery object which can contain any combination of: snapshot id, expiry date, creation date, additional information provided as key/value pairs. See SnapshotManager javadoc.

Snapshot[] system.snapshotManager.getSnapshots(query);

This returns an array of candidate snapshots that match the search criteria. Typically, these would be displayed to the user who can then select which snapshot should be restored.

Restore a snapshot

A snapshot can be restored with Api method SnapshotManager.restoreSnapshot() using its unique id. See SnapshotManager javadoc.

system.snapshotManager.restoreSnapshot(snapshotId);

When this is executed, the current form is replaced with the snapshot and the user is returned to the current page at the point when the snapshot was taken.

Delete a snapshot

This can be achieved using Api method SnapshotManager.createSnapshot().See SnapshotManager javadoc.

String system.snapshotManager.removeSnapshot(snapshotId);

Expired snapshots are also removed periodically by the snapshot maintenance scheduled task.

Example (Javascript)

Create a snapshot using the form id to identify the application and an email address and password to identify the user. The snapshot does not expire.

var args = {};

args.form_id = form.elementName;

args.email = fields.EMAIL_ADDRESS.value;

args.password = EncryptionServices.encrypt(fields.PASSWORD.value); // protect the user’s password by encrypting it

var snapshotId = system.snapshotManager.createSnapshot(args, null);

// optionally set snapshot expiry – 4 weeks

// var expiry = new Date();

//expiry.setDate(lastWeek.getDate() + 28);

//var snapshotId = system.snapshotManager.createSnapshot(args, expiry);

Search for candidate snapshots to be restored. These are then presented to the user in a list – this is field CANDIDATE_SNAPSHOTS - showing the date and time each snapshot was taken.

var query = new SnapshotQuery();

var args = {};

args.form_id = form.elementName;

args.email = fields.EMAIL_ADDRESS.value;

query.fields = args;

var snapshots = system.snapshotManager.getSnapshots(query);

// create a list displaying date/time of snapshot and returning the snapshot id

var list = fields.CANDIDATE_SNAPSHOTS.createCustomList();

for each (var snapshot in snapshots)

{

list.add(DateServices.formatDate(snapshot.creationDate, "dd/MM/yyyy HH:mm"), snapshot.snapshotId);

}

When the user makes a selection, check the password, then restore the form.

var query = new SnapshotQuery();

query.setSnapshotId(fields.CANDIDATE_SNAPSHOTS.value);

var snapshot = system.snapshotManager.getSnapshots(query);

// check the password

var found = false;

for each(var snapshot in snapshots)

{

var snapshotPassword = EncryptionServices.decrypt(snapshot.fields.password);

if (fields.PASSWORD.value == snapshotPassword)

{

// do the restore

system.snapshotManager.restoreSnapshot(snapshot.snapshotId);

break;

}

}

if(!found)

{

event.owner.addErrorMessage("Password incorrect");

}