The hidden power of Profile documents

Profile documents are a useful tool for storing and retrieving user-specific or database-specific values. This tutorial shows how to create a profile form, use @commands and LotusScript to create and edit profiles, and edit profile documents from the Web.

Share:

Julie Forgo, Technical Writer , Lotus

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.



01 December 1997

Profile documents, new in the 4.5 release, are a useful tool for storing and retrieving user-specific or database-specific values that you need to access quickly. You can use Profile documents for quick data retrieval, because they are cached while the database that stores them is open. Profile documents are like other database documents except they are somewhat invisible -- they do not display in views and are not included in a document count for the database. Additionally, a user does not create a profile document from the Create menu; you provide an action or agent that uses LotusScript or the command language to create the profile document and make it available for editing.

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.

Figure 1. Calendar Profile document
Calendar Profile document

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.

Conclusion

Profile documents were created to support the implementation of the Calendar and Scheduling features in Notes, but you can take advantage of the power of the profile in a variety of applications. If your application can benefit from caching settings for all or some documents in a database, give profile documents a try.

Copyright 1997 Iris Associates, Inc. All rights reserved.

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=12659
ArticleTitle=The hidden power of Profile documents
publish-date=12011997