Package com.ebasetech.xi.api

Interface SnapshotManager

public interface SnapshotManager
Interface SnapshotManager contains a number of methods to allow applications to create and restore snapshots.

A snapshot contains all the form state data for an application and all the information required to restore the application at some time in the future. From the user's perspective, this allows them to save their work and continue at some future point; for example when completing a tax return, the user might need to suspend completing the form while she requests additional information from a savings company.

Each snapshot is identified by a unique identifier which is system generated and cannot be modified.

Snapshots can optionally contain any number of snapshot fields. These are key value pairs that are used to provide additional information to the snapshot, for example they might be used to save the form id, the user id, a password or additional security questions.

The following illustrates a typical save/restore scenario:

Save:
The user requests the creation of a snapshot by clicking on a save button. The application then displays a page requesting information that uniquely identifies the user such as an email address - if the user is already signed on, this is probably not necessary. Additional security such as a password and/or additional information may also be requested at this time. The application then calls method createSnapshot(Map, Date) to create the snapshot. The user can continue to work on the form or not as they choose.

Restore:
At some time in the future, the user requests a restore to a snapshot, possibly by clicking on a restore button. The application asks the user to identify themselves - again, this may not be necessary if the user is already signed on. The application then requests a list of candidate snapshots by calling method getSnapshots(SnapshotQuery). This list is displayed to the user, typically showing the date and time each snapshot was created. When the user makes a selection, they are prompted to supply any additional security information such as a password and/or additional information. The application checks this security information against the snapshot and if successful calls restoreSnapshot(String) to restore the snapshot. All state data is restored from the snapshot and the user is returned to the page where the snapshot was created.


Designer Note:
Please note that it might not be possible to restore a snapshot between different versions of the Verj.io software. The system tries to support the restoration of snapshots between different versions, but cannot guarantee that a snapshot saved in one particular version will restore in a newer version.

Know snapshot issues:
It is not possible to restore snapshots saved in V4.4.3 or before. From V4.4.4 snapshots are release independent.

Further documentation.

Since:
V4.4

  • Method Summary

    Modifier and Type Method Description
    java.lang.String createSnapshot​(java.util.Map<java.lang.String,​java.lang.String> snapshotFields, java.util.Date expiryDate)
    Creates a snapshot for the application currently being executed.
    Snapshot[] getSnapshots​(SnapshotQuery query)
    Returns an array of candidate snapshots that match the search criteria specified in query.
    boolean removeSnapshot​(java.lang.String snapshotId)
    Removes the snapshot from the server store.
    void restoreSnapshot​(java.lang.String snapshotId)
    Restores the state of all forms to the specified snapshot.

  • Method Details

    • createSnapshot

      java.lang.String createSnapshot​(java.util.Map<java.lang.String,​java.lang.String> snapshotFields, java.util.Date expiryDate)
      Creates a snapshot for the application currently being executed. The snapshot can then be used in a subsequent restore operation (restoreSnapshot(String)). All state data for the application is saved. Snapshot fields are key value pairs and are used to give additional information to the snapshot. These can be used for many different purposes:
      • Password authentication
      • Security questions
      • Form or application identifier
      • Page identifier
      • User identifier
      • etc....

      Further documentation.

      Javascript example 1. Add form id, user name and password authentication to the Snapshot: 

       var snapshot_fields = {};
 snapshot_fields.form_id = form.elementName;
 snapshot_fields.username = system.securityManager.userName;
 snapshot_fields.password = EncryptionServices.encrypt("myPassword");
 var snapshot = system.snapshotManager.createSnapshot(snapshot_fields, null);
      Javascript example 2. Add security questions to the Snapshot and an expiry date: 
       var snapshot_fields = {};
 snapshot_fields.color = fields.COLOR.displayValue;
 snapshot_fields.pet = fields.PET.displayValue;
 snapshot_fields.maiden_name = fields.MAIDEN_NAME.displayValue;
 var expiry = new Date();
 expiry.setDate(expiry.getDate() + 30);
 var snapshot = system.snapshotManager.createSnapshot(snapshot_fields, expiry);
      Parameters:
      snapshotFields - - Map of additional information for the snapshot.
      expiryDate - the expiry date for this snapshot or null if the snapshot does not expire.
      Returns:
      the created snapshot id
      Since:
      V4.4
      See Also:
      SnapshotManager

    • getSnapshots

      Snapshot[] getSnapshots​(SnapshotQuery query)
      Returns an array of candidate snapshots that match the search criteria specified in query. These snapshots could then be offered to the user and when a selection is made, method restoreSnapshot(String) can be called to implement the restore.

      Further documentation.

      Javascript example 1. Find a snapshot with a specific id: 

       var query = new SnapshotQuery();
 query.setSnapshotId("123456789-HHH-BBB");
 var snapshots = system.snapshotManager.getSnapshots(query);
 if(snapshots.length == 1) 
 {
      //found a match, do something...
      var snapshot = snapshots[0];
      .....
 }
      Javascript example 2. Find snapshots for the current form and for current user which have not expired: 
       var query = new SnapshotQuery();
 var snapshot_fields = {};
 snapshot_fields.form_id = form.elementName;
 snapshot_fields.username = system.securityManager.userName;
 query.setFields(snapshot_fields);
 var snapshots = system.snapshotManager.getSnapshots(query);
 if(snapshots.length > 0) 
 {
      //found matches, do something...
      for each(var snapshot in snapshots)
      {
          //do something with snapshot
          .......
      }
 }
      Parameters:
      query - information used to filter the list of returned snapshots. See SnapshotQuery.
      Returns:
      an array of candidate snapshots
      Since:
      V4.4
      See Also:
      SnapshotManager

    • restoreSnapshot

      void restoreSnapshot​(java.lang.String snapshotId)
      Restores the state of all forms to the specified snapshot. This includes the current form and any other forms that may be in the form "stack" when call form has been used. The user can then continue working with the restored data.

      Further documentation.

      Javascript example: 

       var snapshotId = fields.SNAPSHOT_ID.value;
 try
 {
      system.snapshotManager.restoreSnapshot(snapshotId);
 }
 catch(e)
 {
      log("Error restoring snapshot: " + e);
 }
      Parameters:
      snapshotId - the id of the snapshot to be restored (see Snapshot.getSnapshotId())
      Since:
      V4.4
      See Also:
      SnapshotManager

    • removeSnapshot

      boolean removeSnapshot​(java.lang.String snapshotId)
      Removes the snapshot from the server store.

      Further documentation.

      Javascript example: 

       var snapshotId = fields.SNAPSHOT_ID.value;
 try
 {
      system.snapshotManager.removeSnapshot(snapshotId);
 }
 catch(e)
 {
      log("Error removing snapshot: " + e);
 }
      Parameters:
      snapshotId - - snapshot id to remove
      Since:
      4.4
      See Also:
      SnapshotManager