You can either have a single profile document for a database, or multiple profile documents that match a key you specify -- for example, an @username key that creates one profile document for each user of a database, or a key that specifies a different profile document for each day of the week. Whether you use one profile document for a database or use multiple profile documents depends on your design needs. Use a single profile document to contain settings that all documents in the database need, such as environment variables. Use multiple documents for more customizable settings, such as user preferences.

For an example of a single profile document created for a database, look in the 4.5 mail template (Std45Mail.ntf) or the Notes mail template for 4.6 (Mailn46.ntf). Users with a mail application based on either template use an action to modify a Calendar Profile document that stores settings for their personal calendar. The profile document, among other things, specifies user preferences such as a default duration for meetings and alarm settings. Each time a user creates a new mail memo, Notes checks the settings in the calendar profile to retrieve this user-specific information. Because the profile settings are cached when the database is open, there is no performance hit as there would be if Notes had to retrieve the settings from disk with such frequency.

The following illustration shows some settings from the Calendar Profile.

The Domino 4.6 Certificate Authority template (certca.ntf) for system administrators includes another example of a single profile document created for a database. In this case, the profile document stores configuration settings for a Certificate Authority database. In addition to the performance advantages of caching the environment variables, the profile document provides an easy mechanism to make sure that one and only one document of this type is created for the database.

An example of profile documents created for each user of a database might be an interest profile that each user can use to specify areas of interest. A user is then notified when topics matching the selection criteria are added to the database. For example, a product manager is notified when topics referring to her product are mentioned in a customer discussion database.

An example of multiple profile documents based on a key other than username is a profile type that stores state-specific tax information for processing invoices.

Creating a form for profile documents
There is nothing magical about the form used for creating profile documents. It is how documents created from the form are displayed and how values are passed back and forth that marks a document as a profile. Only one profile of a given form can exist for each user of a database. Or, only one profile document can exist for a database if that form is available to all users. You need to have at least Author access in the access control list (ACL) of a database to create a profile document that is available to all users.

So, to create a profile document, start by designing a form that contains the profile fields. For example, to create an Interest Profile for a Discussion database, add fields for the user's name as well as fields for the interest criteria for matching documents.

After creating the form, uncheck the form property "Include in Menu" and "Include in Search Builder" as these options would defeat the purpose of having an invisible document.

Creating and editing a profile document using @commands
You can create or edit a profile document using @Command([EditProfile]) or @SetProfileField. You can retrieve field values from an existing profile document using @GetProfileField. For full syntax descriptions, see the topics for each command in the Notes online Help.

You cannot delete a profile document using an @command or @function. Use LotusScript if you must delete a profile document.

Creating or editing a profile document using EditProfile
The key piece of syntax to note when using the EditProfile command is that if you specify the optional key parameter, username, multiple documents matching this form are available for the database. By omitting this optional parameter, you are creating a single profile document for use by all users of the database.

This formula creates a new Interest Profile document for a user to edit. If a profile already exists for the user, this formula opens it in edit mode.

@Command([EditProfile];"Interest Profile";@UserName)

This formula when used in the Public Address Book opens the Server\Setup Profile document in edit mode. Because there is no key specified for multiple profile documents, the result is a single profile document for the Public Address Book database.

@Command([EditProfile];"Profile")

Note that the EditProfile command is not supported for editing profile documents on the Web. A section at the end of this article describes special considerations for making profile documents available to Web users.

Setting and retrieving field values from a profile document
Use the SetProfileField and GetProfileField commands to set and retrieve field values from a profile document. A SetProfileField command also creates a profile document if none exists.

The following formula adds a project category to the interest profile of a discussion database so that every user is notified when discussion topics are posted in this category.

@SetProfileField("Interest Profile"; "ProfileCategories"; "Project X"; @UserName)

The following formula gets the value from the ArchivedLife field of the Archive Profile document in the mail database and displays it in a dialog box.

AL:= @GetProfileField("Archive Profile"; "ArchivedLife"; @username);
@Prompt([OK]; "The archive life of documents is: "; AL)

Creating and editing a profile document using LotusScript
If you prefer scripts to formulas, use LotusScript routines to create and edit profile documents. The EditProfile method of the NotesUIWorkspace class produces the same result as the @Command([EditProfile]) command used in a formula. The first argument names the profile document, and the second argument is used for optionally specifying a key for generating multiple profile documents.

For syntax descriptions, usage notes, and further examples of these LotusScript constructs, see the Notes online Help.

The following script uses the EditProfile method to create an Interest Profile for a user to edit. If one already exists, this method opens the document in edit mode so the user can enter new values for the profile.

Dim workspace as New NotesUIWorkspace
Dim session as new NotesSession
Call workspace.EditProfile("Interest Profile", session.UserName)

Note that this front-end class is not supported for editing profile documents on the Web. A section at the end of this article describes special considerations for making profile documents available to Web users.

Setting and retrieving field values from a profile document
To set or retrieve field values for a profile document with a script, use the GetProfileDocument method to get a handle to the document. You can then retrieve values from the document or set new ones, just as you would with any document.

Dim session as New NotesSession
Dim db as NotesDatabase
Dim doc as NotesDocument
Set db=session.CurrentDatabase
Set doc=db.GetProfileDocument("Calendar Profile")

Checking the properties of a profile document
A document named Profile may not in fact be a profile document. For example, the Interest Profile document created in the Notes and Web Discussion template gathers user-specific information about what discussion threads a user wants to monitor. It is not, however, a true profile document that caches the contents of the document.

Use the IsProfile property for the NotesDocument class to determine if a NotesDocument object is a profile document. The property returns a read-only value of true or false. If a document is a profile document, the Key property returns the key -- for example, the user name associated with the profile. If there is no key specified -- that is, when there is just one profile document for the database -- the Key property returns an empty string. Use the NameOfProfile property to retrieve the name of the profile document.

The following script returns information about the Calendar Profile in a mail database.

Dim session as New NotesSession
Dim db as NotesDatabase
Dim doc as NotesDocument
Set db=session.CurrentDatabase
profileKey=InputBox("Profile name?")
profileUserName=InputBox("This profile belongs to (key).")
Set doc = db.GetProfileDocument(profileKey, profileUserName)
If doc.IsProfile Then
Messagebox "Profile name: " & doc.NameOfProfile & Chr (10) &_
"User name (key): " & doc.Key, ,doc.NameOfProfile
End If

Deleting a profile document
The following script deletes the Calendar Profile document from a user's mail application.

Dim session as New NotesSession
Dim db as NotesDatabase
Dim doc as NotesDocument
Set db=session.CurrentDatabase
Set doc=db.GetProfileDocument("Calendar Profile")
Call doc.remove(0)

Editing profile documents from the Web

Using profile documents in applications served on the Web presents a challenge. You can use LotusScript calls to the back-end or @GetProfileField to access profile documents from the Web, but allowing users to access and edit their profile documents on the Web requires a bit of tinkering. The Calendar Profile document in the Notes/Web combined mail template for Notes 4.6 (mailc46.ntf) illustrates the technique for allowing users to edit profile documents from the Web.

In the Notes client, users use the EditProfile commands to access and edit their personal settings in the CalendarProfile. These commands do not work from the Web. The differences are distinct enough that you must create separate forms for the Notes and Web clients using your application.

So the first step of the workaround is to create separate profile forms for Notes and Web clients. The Notes client profile form contains all of the fields, while the Web client profile form acts as an interface to the Notes client form. Be sure to add a SaveOptions field to the Web version of the profile form with a default value of "0" so that documents created with that form do not get saved. You will instead pass field values to the Notes client profile form and save them there.

After you create the form for the Web profile, perform the following steps:

1. Create a means to compose the Web version of your profile document. Do this by creating action buttons or action hotspots. Use the action formula
   
   @Command([Compose];"YourWebProfileFormName")
   
   For an example, take a look at the Preferences hotspot that exists in the (web view template) subform found in the Notes/Web mail template.
2. Create a WebQueryOpen agent to initialize values.
   
   Since this action composes a brand new document, you need to initialize a good number of fields. In the WebQueryOpen agent, access the Notes profile document using the NotesDatabase.GetProfileDocument method. Copy the items that you want the user to edit or read to the ContextDocument of the WebQueryOpen agent.
   
   Use the WebPreferencesOpen agent in the combined mail template as a reference for how to do this.
3. Create a WebQuerySave agent to store values.
   
   Since you added the SaveOptions field to the form and set its value to "0", the current document will not be saved. However, you need to write any values that the user enters back to the Notes profile document. As you did in the WebQueryOpen agent, you access the profile document using the same NotesDatabase.GetProfileDocument method. Copy the items of interest from the ContextDocument of your WebQuerySave agent back to the Notes profile document. Be sure to save the Notes profile document; otherwise, the users' changes are lost.
   
   Use the WebPreferencesSave agent in the combined mail template as a reference for how this is done.

ABOUT THE AUTHOR
Julie Forgo, a technical writer with more than ten years' experience, has documented various aspects of Notes for the past four years. Her area of expertise is Domino application development, and she recently co-authored a revision of the Best Practices: Application Developer's Guide. When not busy extracting feature details from developers, Julie chases after her two children and performs miracles with a hot-glue gun.

Copyright 1997 Iris Associates, Inc. All rights reserved.