When was the last time you were working on a last-minute report to your manager, and after spending hours typing, formatting, and proof-reading, all of a sudden your machine freezes or some other unexpected event happens that makes you lose all your work? And right at that minute, you remember âOh no, I've forgotten to save the document!â So you ask yourself (it's 2 AM, and you must be alone, so you might as well talk to someone!), "I can either start to work on the report from scratch, or should I just start updating my resume?â If anything like this ever happened to you, you probably wished that you had a guardian angel who saved your work from time to time so that you can retrieve it when such unexpected incidents happen.
AutoSave is that guardian angel! It is one of the many cool features that we've introduced in Notes 7.0. With AutoSave enabled, Notes documents are saved (on a timer event set by the user) to a local database. This way, if Notes or your computer crashes for any reason, you have a copy of your latest work, ready to be recovered.
Are you ready to take a tour of AutoSave to see how we designed it, and how you can enable and use it? If so, read on! This article assumes you're an experienced Notes user. For more information about all the features in Notes 7.0, see the developerWorks: Lotus article, "New features in Lotus Notes and Domino Designer 7.0."
When we started developing AutoSave, we had the following goals in mind:
- Users must be able to AutoSave documents on fixed intervals that are specified by the user.
- Users must be able to recover saved documents when they start the Notes client after it fails for any reason.
- AutoSave must be secure so that no user information is left unencrypted.
- AutoSave must be fast, and must avoid any extra server activity.
- Users must be able to turn AutoSave on and off, as controlled by administrators through a policy.
A typical scenario
As we started to design AutoSave, we imagined this scenario: You are happily working on a document when something unexpected happens and you lose your work. Now what?
Several ideas came to mind. For instance, we could start a timer and on some constant interval we'd save the document the user is working on. We soon discovered that this solution had numerous issues. First, what if you have 1,000 users who choose to set their AutoSave interval to 1 minute, and all of them are hitting the server every minute? This would cause major performance degradation, and lead to longer response times from the server. Second, what if you're not done with your document, and it's in a "half-baked" state that you don't want anyone else taking a peek at? What if you have only writer access and no delete capabilities? What if your database has some validation code that requires various fields to be filled before the document can be saved, and will produce all sorts of errors if you try to save before that? What if the form has code in your Post Save or Query Save events that sends emails to others saying the document is ready for review? What if...well, you get the idea. As you can probably guess, we didn't go down that path.
Another thought was similar to the first one, but we do a "quiet" save (a save that doesn't fire up any events) of this document to a local encrypted database. After the user starts the Notes client after a failure, we check to see whether or not there are any documents available in this database. If so, we'd present them to the user to decide whether or not to recover any of them. That's the path we took, and it worked!
By taking this approach, we avoid hitting the server by using a local database. We also provide a secure solution (encrypted database), prevent errors from showing up or emails being sent while saving (because weâre not firing any events), and provide total flexibility to you to decide whether or not you want to recover the document you have been working on.
Working with AutoSave involves the following:
- Enabling AutoSave on the client
- Enabling AutoSave on a form
- Normal AutoSave operations
- Recovering your autosaved document
The following sections explain these activities in detail.
Enabling AutoSave on the client
AutoSave is not enabled by default when you install Notes 7.0. The reason it's not is that users may not know whatâs going on when they first see AutoSave in operation. Also, some users may be using a slower machine, on which "autosaving" large documents may take significant time. So, if you want to activate AutoSave, you must enable it through a new option in the User Preferences dialog (see figure 1):
Figure 1. User Preferences dialog
We've added a checkbox to enable/disable AutoSave, and also a field to set the timing interval. This interval can be anywhere from 1 minute through 999 minutes. These AutoSave user preferences options correspond to three variables in the client's Notes.ini file. The following table shows which options map to which Notes.ini variables:
|Notes.ini setting||User preference setting|
|AUTO_SAVE_ENABLE = n||When set to 1, AutoSave is enabled. When set to 0, AutoSave is disabled.|
|AUTO_SAVE_INTERVAL = <mins>||Sets the interval between autosaves.|
|AUTO_SAVE_USER,<Abbreviated User Name>=<Database name relative to the data dir>||Resolves naming conflicts (see later in this article for an explanation).|
Enabling AutoSave on a form
As we mentioned earlier, a quiet save doesn't fire up any events. The reason we use a quiet save for AutoSave is to ensure that AutoSave is a "seamless" operation -- you enable it and then forget about it until the unexpected happens, then it kicks in telling you that you have one or more documents to recover. Firing up such events can (and usually does in some situations) produce errors if the document isn't complete. These events can also send emails, and can lead to unexpected results. So we don't fire up these events while autosaving a document. So you may well be wondering at this point, what if the form is dependent on these events? The answer is simple: it won't work!
To address this, we've added a new Form Properties option that determines whether or not the form can be autosaved. This allows the template developer or the application designer to test their application and see whether or not it can be safely autosaved and recovered. If so, they can open the Form Properties infobox, go to the first tab, and select the Allow AutoSave checkbox (see figure 2):
Figure 2. Allow AutoSave option
Only documents created from forms with Allow AutoSave selected can be autosaved. This is the only way to ensure that the document can be recovered after it has been autosaved. Many Notes/Domino applications have code in their Save and Post Save events that create items, or perform validations that are checked at load time. Because we can't execute these events while autosaving the document, none of this will take place, and the autosaved document will be in a "bad" state. This could lead to failing to load the document after recovery.
If your application does write items on save events, and itâs dependant upon these item, you may need to add code in your Query Open event to put defaults for those items. You can even do special handling only for documents that are recovered by looking for an item called $AutoSaveRecovered. This item will only be available for recovered documents up until the Post Open event, and will be deleted after that.
Another way to programmatically disable AutoSave on individual documents is by adding the item $DontAutosave. This item prevents AutoSave on that document. If you remove $DontAutosave, the document can again be autosaved.
NOTE: In Notes/Domino 7.0, the only shipping template form that is enabled for AutoSave is the Memo form.
Normal AutoSave operations
Now that you've enabled AutoSave in the Notes client and also in the form, you're ready to roll. After you open a document and start typing, a timer is started thatâs waiting for the interval you've set to pass. This timer starts only when you modify the document; this prevents disk activity when youâre merely reviewing the document.
After the interval passes, AutoSave performs a quiet save without firing any events (as mentioned earlier). The copy of the saved document that appears in the AutoSave database on your local disk includes several additional fields that will help AutoSave recover this document in the event of a failure. These fields are as follows:
|$AutoSaveDataBase||Name of the database in which the document resides.|
|$AutoSaveDocTitle||Title of the document.|
|$AutoSaveNoteID||Note ID of the document.|
|$AutoSaveOrgDocRL||Resource link that we use to open the document.|
|$AutoSaveServer||Server name where the database replica resides.|
|$AutoSaveTime||Last Modified Time of the document.|
After we start autosaving, we post the following message on your status bar: Autosaving document : <document title>...
And when the AutoSave operation is done, we post another message on your status bar (see figure 3):
AutoSave complete : <document title>...
Figure 3. AutoSave message
After you see that AutoSave is complete, your data is saved and can be recovered the next time you launch Notes after a failure. Does this mean you're going to have tons of documents in this local database? Not quite! After you save the document, cancel out of it, or email it, we delete the autosaved copy to save space in your AutoSave database. This also makes it easier for you to view only those documents you're most likely to want to recover.
At this point, you're covered in the event of a failure because AutoSave will save this document at regular intervals (which hopefully occurs not too long before the failure happens). But what if you suspect that things are not going well while you're editing a document (screen flickering, cursor sticking, blue boxes flashing, and so on)? In these situations, you can force an AutoSave at any time. To do this, go to the File menu, select AutoSave, and then click AutoSave Now. This forces an immediate AutoSave.
Recovering your autosaved document
Here is the sequence of events that happen when you restart your Notes client after a failure. On client startup, after you authenticate, we check to see whether or not there are any documents in the AutoSave database. If there are, we prompt you to specify whether or not you want to recover the unsaved work (see figure 4).
Figure 4. Unsaved Work dialog
If you choose Yes, we prompt you to specify which unsaved documents you're interested in restoring. Then you'll see a dialog box similar to figure 5, listing all the documents that can be recovered and offering you several recovery choices:
|Recover||Recovers the selected document and removes it from the list.|
|Recover All||Recovers all documents without prompting for each document, and if no errors, closes the dialog.|
|Delete||Deletes this document from the local AutoSave database, and makes no changes to the original document.|
|Delete All||Deletes all documents from the local AutoSave database, and makes no changes to the original document.|
Figure 5. Recover Unsaved Documents window
The fields in the Recover Unsaved Documents window show the following information: the time the document was autosaved, the title of the document, the pathname/filename of original database, and the name of the server on which the database resides.
If we can't access any replica of the original Notes database, we can't recover the document, so we simply leave the note as is; you can then retry recovery at a later time. If the document has been modified since the last AutoSave, we inform you that the original document has been modified from the last time we crashed, and give you the option to overwrite or keep the new one. If you choose to recover the document, we open the document in Notes and offer the option to either discard the changes or save them. But AutoSave will not automatically save the document on your behalf after recovery.
The AutoSave database
We originally designed AutoSave to use a single database (Autosave.nsf) created from Autosave.ntf. This database was encrypted. However, we eventually encountered a potential problem. During early testing, we found that in many Notes/Domino environments, multiple users use the same Notes Data directory, with each user having a separate Location document. By default, AutoSave.nsf was placed in the user's Data directory and encrypted (using medium encryption). So when the first user creates the first AutoSave database, it would be encrypted with that user's key. As a result, no other users could use this database, thus AutoSave for them would be disabled.
To avoid this situation, we decided to create the AutoSave database using a similar naming convention we use to name mail files. To do this, we prepend as_ at the beginning of the database name. For example, for Alaa Mahmoud, the AutoSave database name will be as_Amahmoud.nsf. If a database with that name already exists, we append 1 to the name, and recheck. If that name exists, we append 2, and so on until we have a unique name for the AutoSave database.
Resolving name conflicts
With our naming solution, conflicts will happen for names such as John Smith, Jane Smith, Jen Smith, Jon Smith, and so on. To make sure we get the right database for the current user, after we create a database for a user, we create the following entry in the user's Notes.ini file:
AUTO_SAVE_USER,<Abbreviated User Name>=<Database name relative to the data dir>
This allows the following sequence of events to happen. The user starts Notes with a particular ID. We check to see whether or not an entry for this user name exists in the Notes.ini. If an entry exists, we use the database name in that entry. If that database doesn't exist, we create a new one (in case the user deleted the database). If the user doesnât have access to this database, the user receives an error and AutoSave is disabled. If we couldn't find an entry with the user's name, we create an entry and a database, based on the naming convention described previously in this section.
If the user switches IDs, Notes closes all opened documents. Therefore, we don't have an issue with open autosaved documents.
Setting AutoSave options using policies
For administrators who want to enable or disable AutoSave (or who want to make sure users have the same standard interval between AutoSaves), this can be done via a policy document. To do this, open the Domino Admin client and select File - Open Server. Then enter the name of the server that you want to administer. This opens the Domino Directory on the server. Select Settings from the left navigation panel. Then either select Add Settings - Desktop/Setup Setting, or select an existing Desktop Settings document and click Edit Settings. After you open the document, select the Preferences - Basics tab to display figure 6:
Figure 6. Desktop Settings screen
Complete the two AutoSave-related options:
- Enable AutoSave enables/disables the AutoSave feature for users. When disabled, users will not be able to use AutoSave.
- AutoSave every N minutes sets the time interval (in minutes) between AutoSaves.
In this article, we have learned that AutoSave is a pretty cool feature. It saves your work from the unexpected, itâs user-settable from the User Preferences, it's also administrator-settable through policies. Designers need to enable their forms for AutoSave after making sure their forms are not dependant on any events that we donât fire up. Finally, we've learned that AutoSave is fast and secure through the use of an encrypted local database.
So now when there's an unexpected crash (and how many of them are "expected"?) while you're working on a Notes document, don't worry -- AutoSave to the rescue!
- For more information about all the features in Lotus Notes 7.0, see the developerWorks: Lotus article, "New features in Lotus Notes and Domino Designer 7.0."
- And for more information about new features in Lotus Domino 7.0, see the article, "New features in Lotus Domino 7.0."
- See the Lotus Notes/Domino product page for more information about the Lotus Notes and Domino products.
- Get involved in the developerWorks community by participating in developerWorks blogs.