Snapshots
See also: Javadoc for SnapshotManager, Snapshot, SnapshotQuery
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 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.
The
Snapshot Manager provides the ability to:
This is
done using Javascript 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:
Snapshots
can be searched with Javascript 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.
A snapshot
can be restored with Javascript 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.
This can be
achieved using Javascript method SnapshotManager.createSnapshot().See SnapshotManager
javadoc.
String system.snapshotManager.removeSnapshot(snapshotId);
Expired
snapshots are also removed periodically by the snapshot
maintenance scheduled task.
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");
}