All about AutoSave in Lotus Notes/Domino 7

Oops, it's gone -- all your hard work for the last hour has been lost due to a computer crash! Too bad you didn't think to save it along the way. Well, now you don't have to, thanks to the new AutoSave feature introduced in Lotus Notes/Domino 7.

Alaa Mahmoud, Software Engineer, IBM, Software Group

Alaa Mahmoud is a Software Engineer who has been with IBM since the mid-1990's. He has served as Technical Lead with the Lotus Notes Core Services team and the Editor team, working with Lotus Notes since R5. Currently Alaa is a Team Lead for the Lotus iNotes Total Cost of Ownership (TCO) team, which oversees administration, server performance, server infrastructure, and customization initiatives. Alaa is an expert in software internationalization, especially for bidirectional languages (Arabic and Hebrew).



23 August 2005

Also available in Russian Japanese

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."

Designing AutoSave

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.


Using AutoSave

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
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 settingUser preference setting
AUTO_SAVE_ENABLE = nWhen 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
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:

Field nameDescription
$AutoSaveDataBaseName of the database in which the document resides.
$AutoSaveDocTitleTitle of the document.
$AutoSaveNoteIDNote ID of the document.
$AutoSaveOrgDocRLResource link that we use to open the document.
$AutoSaveServerServer name where the database replica resides.
$AutoSaveTimeLast 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
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
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:

OptionDescription
Recover Recovers the selected document and removes it from the list.
Recover AllRecovers all documents without prompting for each document, and if no errors, closes the dialog.
DeleteDeletes 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
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>

For example:

AUTO_SAVE_USER,Alaa Mahmoud/Westford/IBM=as_AMahmoud2.nsf

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
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.

Conclusion

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!

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus
ArticleID=92466
ArticleTitle=All about AutoSave in Lotus Notes/Domino 7
publish-date=08232005