This just in! Understanding database subscriptions

This article introduces database subscriptions, also known as Headlines. It covers how to set up and use subscriptions, performance implications, and application design tips to designate the information a subscription delivers.


Cara Haagenson, User Assistance Writer, Lotus

Cara Haagenson is a User Assistance Writer for Lotus, where she has worked for over a year. She is a member of the Notes Client team and writes online documentation and release notes. She is also a member of the Customer Contact Team.

01 December 1999

Also available in Japanese

Wouldn't it be great if you could automatically receive real-time information on the topics you care most about, without having to manually open databases and scan through information that is irrelevant to you? Luckily, with Notes R5 you can. Database subscriptions, also known as Headlines, give you the ability to subscribe to and receive current updates from your favorite Notes databases.

This article introduces you to database subscriptions and how they can be beneficial to you as an end user, as well as a database designer. You will learn how:

  • To set up and start using database subscriptions in the client
  • The client works with Domino servers to send you the correct database subscription results
  • The performance of the client and Domino servers are affected when database subscriptions are enabled
  • A database designer can designate what information a user can monitor within the database

Subscribing to databases

Most likely, the first thing you see when you open the Notes client is the Welcome Page, a single-source page where you can bring together information that is important to you. By default, the Welcome Page is set to the Basics style, but you can customize it to display such things as your mail inbox, your calendar view, and even your favorite Web site. One of the options you can choose to add to your personalized Welcome Page is database subscriptions. A database subscription is a document that represents the information you choose to monitor in any given Notes database, provided you have proper access to the database or to the server on which it resides. By default, you already have a subscription to your mail database that notifies you when you have new mail.

For the purposes of this article, we will show you how to customize the Welcome Page to display database subscription results.

  1. Select "Create new page style" from the style list in the upper right corner of the Welcome Page. If you already have a personalized page set up, click the Options button that appears next to the Welcome Page style list.
  2. Click the Basics tab, give your Welcome Page a name in the "Page name" section, and select a layout style for your Welcome Page in the Layout section.
  3. Click the Content tab, and then click inside a frame in the "Select a frame" section.
  4. Choose "Database Subscriptions" from the content list in the "Frame content" section, and click OK.

Once you are set up to receive database subscription results on your Welcome Page, you receive those results in an outline form on the Welcome Page.

Here is an example of a Welcome Page that is set up to display database subscription results for new mail. As you can see, the designer of the Mail database chose to have the name of the sender and the subject of the mail message appear in the frameset.

Figure 1. Welcome Page
Welcome Page

Now, how do you actually create a database subscription? First, you should know that there may be some restrictions for subscribing to specific Notes databases and/or servers in your organization. The administrator determines which servers can support database subscriptions, and which databases on those servers allow monitoring. For example, an administrator may not allow you to subscribe to a database on a server that is frequently used by multiple users, because it can slow down the performance of the server. As mentioned earlier, the database designer can also choose what he or she wants monitored in a database. For example, the designer can enable the monitoring of all documents except for ones that are stored in a private view. The designer can also disable the monitoring of an entire database. If you try to create a subscription to a database to which you are denied access, you will see an error message stating that you cannot create a subscription.

Provided you have the proper access to a database, you need to open the database and fill out a subscription form.

  1. Open the database(s) you want to subscribe to and choose Create - Subscription.
  2. In the Subscription form, select the options you want to be notified of in the database.
  3. Click OK or Save.

As you go through different databases filling out subscription forms, you may notice that forms differ. Some may have different selections to choose for monitoring, some may be in different colors, some may even have different fonts and headings. The database designer chooses what you as an end user can monitor in the database, and may design the form in any way he or she chooses. If the database designer did not customize a subscription form, the default form stored in headline.nsf automatically opens when you choose Create - Subscription.

Next, make sure Notes is set up to check for new subscription results.

  1. Choose File - Preferences - User Preferences.
  2. Click Basics and under "Startup Options" select "Check subscriptions."
  3. Click OK.

After you subscribe to different databases, you can view your database subscription forms in the Database Subscriptions (a.k.a. Headlines) database (headline.nsf), which is located in your Favorites folder on the Bookmark bar. Headline.nsf is automatically created from the template headine.ntf and is located in your Notes data directory. If you do not see the Database Subscriptions (or Headlines) bookmark in your Favorites folder, you can choose File - Database - Open and open headline.nsf from your Notes data directory.

Figure 2. Database Subscriptions
Database Subscriptions

Along with the subscription documents, headline.nsf stores the default subscription form necessary for setting up a database subscription, the subscription results retrieved for each event you choose to monitor, and a frameset for viewing the subscription results. When you view database subscription results, each result has a title that you give it and views specified by the database designer, which are displayed in the subscription frameset. Once you see the results in the frameset, whether it be on the Welcome Page or in headline.nsf, you can click each one to view the document you requested without launching the database the document is residing in.

Once you have subscribed to databases, you can control the management of your subscriptions via the Subscriptions Options view in headline.nsf.

To see the Subscriptions Options view, click Customize in the "Database Subscriptions" frame on the Welcome Page, or click "Subscription Options" in headline.nsf.

Figure 3. Subscription Options
Subscription Options

From the Subscriptions Options view you can enable some subscriptions and disable others, you can choose when to have Notes automatically delete results from headline.nsf, you can even choose to disable all subscriptions one week, but enable them the next. Just because you have subscribed to databases doesn't mean you have to enable monitoring. If you disable checking subscriptions at any time, Notes saves the subscription document until you actively delete it from headline.nsf. For more information on managing database subscriptions, refer to the topic "Database subscriptions" in Notes 5 Help.

How does the client retrieve database subscriptions from Domino servers?

You've set up your Welcome Page to receive subscription results, you've subscribed to a couple of Notes databases, now all you have to do is wait for the client to retrieve your subscription results. But, how does the client know what information it should take from the server? For the power user, designer and/or administrator, this section describes what happens behind the scenes when a client retrieves subscription results.

The following diagram illustrates how the Notes client and Domino server work together to send and retrieve database subscriptions. The text following the diagram explains the data flow illustrated in the diagram.

Figure 4. Subscription diagram
Subscription diagram

(1) When you complete a subscription form, a Notes formula is created from a formula field named $HLFormula on the $Subscription form. The formula determines which documents will be monitored in the database. When you save the form, the formula that is created is saved as an event definition, which can then be sent to the server. You can view the formula that is created by clicking the Advanced tab on the subscription form.

(2) The client registers the new event definition over the network, via a hidden background task, and stores it in a monitor list. During this process, a single unique ID for the client and an ID used to identify the registered event definition are created for each event definition. Once registered, the event definition is intended to stay registered until you no longer want the information. Either the event definition expires if it hasn't been used on the client side after 21 days from the registration date, or you can delete or disable the subscription on the client.

(3)The server retains information about the event definition in its monitor list. When a change is made to a document in the database on the server, the event definition determines whether that particular document change needs to be recorded. If it does then NSFNoteUpdate, which is the API function that writes the in-memory version of the document to the server, records summary information about the document. The summary information becomes the subscription result that is stored in the subscription events list.

(4) The client polls the server for database subscription results twice as often as it checks for new mail. For example, if you set your preferences to check for mail every four minutes, the client checks for subscription results every two minutes. If there are updates since the last poll, the server returns them to the client, via the background task, and stores the results in headline.nsf. Once they are in headline.nsf, the subscription results are stored in hidden views that correspond to each of the subscription documents. These results are then displayed on the Welcome Page, or you can view them in headline.nsf.

When the client registers an event definition for a subscription over the network, it initially tries to use the server that the database was residing on when it was first subscribed to. If that server is not responding, it fails over to the next replica and continues down the list in the Domain Catalog. If there aren't any servers in the list responding, if they do not allow database subscriptions, or if you do not have access to any of the servers, it fails over to your local replica. A history of the servers accessed and the time and date the servers were last accessed is recorded in each subscription document stored in headline.nsf.

Performance issues with database subscriptions

There are a couple of performance issues related to using database subscriptions in Notes R5. On the client side, regardless of how many database subscriptions you have, polling servers for updated events does slow down the performance of Notes, because the client is on a schedule to poll the servers. It is recommended that if you don't want to monitor databases for any period of time, disable them by unchecking "Check subscriptions" in User Preferences. Disabling the checking of database subscriptions can save up to four megabytes of memory. As mentioned earlier, you have a New Mail subscription already created for you in Notes and it is enabled. If you don't plan on using it, disable it to keep the performance of your client optimal.

On the server side, the server is smart enough to recognize identical formulas/event definitions that could be coming in from multiple clients. If there are identical formulas, the server stores in its memory one copy of the formula along with a list of the client IDs the formula is associated with. This is to make sure subscriptions don't significantly slow down the server by checking the same formula multiple times. Also, by keeping the event definitions on the client, the server can discard event information if the memory holding the events becomes excessive, or if the client doesn't check for event information after 21 days from the registration date.

Customizing your database subscription form

As a database designer, you may want to customize your subscription form, $Subscription. The advantage to customizing the subscription form is that you can be very specific with what you want monitored in your database. If you do not create a custom form for database subscriptions, the generic subscription form in headline.nsf is automatically used, as shown here:

Figure 5. Default subscription form
Default subscription form

The easiest way to customize a subscription form for your database is to select and copy the default subscription form from headline.nsf, and then paste the form into your own database.

  1. In Domino Designer R5, choose File - Database - Open.
  2. Select Headlines (headline.nsf) and click Open.
  3. Click Forms.
  4. Select $Subscription and choose Edit - Copy.
  5. Choose File - Database - Open, select the database you have created, and then click Open.
  6. Click Forms and then click in the right frame to get focus.
  7. Choose Edit - Paste.

Copying the default subscription form and pasting it into your own database ensures that you have all of the necessary fields needed for subscriptions. Once you have the form in your own database you can edit it.

Note: For more information on customizing the subscription form, see the topic "Formula fields" in Domino 5 Designer Help.

Here's some examples of different subscription forms, just from within Notes itself. The Notes mail subscription form, from the Mail (R5.0) template, has options specific to mail messages:

Figure 6. Mail subscription form
Mail subscription form

The Discussion subscription form, from the Discussion - Notes & Web (R5.0) template, uses different graphics along with some different selection fields:

Figure 7. Discussion subscription form
Discussion subscription form

Customizing your subscription result views

You can also determine which views appear in the frameset when the client receives subscription results. You can create either a $HeadlinesView view in the database being subscribed to, or a $HLHeadlineView text field on the subscription form containing the name of the view in the database being subscribed to. If you do not specify a special view, or add a view specification to the subscription form, the database's default view is used to display the subscription results on the Welcome Page or in headline.nsf.

For example, the New Mail subscription only displays the name of the sender and the subject of the message on the Welcome Page by using the special hidden $HeadlinesView view in the mail database. However, your inbox default view displays the name of the sender, the date the message was received, the size of the message, and the subject of the message.


In a world where it is important to find out new information as it's created, database subscriptions can deliver real-time data without wasting time and causing aggravation. In future releases of Notes you can expect improved performance with the client while using database subscriptions, including improved failovers. You can also expect to find user interface enhancements for ease-of-use. The Welcome Page will make it easier for you to view and create database subscriptions and you will be able to share subscriptions that are provided by the administrator.



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

ArticleTitle=This just in! Understanding database subscriptions