The IBM Lotus Notes and Domino Out of Office service: Best practices

Abstract: This article describes best practices with respect to configuring, setting up, using, and troubleshooting the Lotus Notes/Domino 8 Out of Office Service feature. The information presented here is based largely on Lotus Technical Support experience acquired during the past year, the first year of this feature’s life.

Introduction

I became very interested (some might argue mildly obsessed ) with the Lotus Notes/Domino Out of Office feature when I started noticing that Lotus Support was receiving quite a few calls about it every day. In fact, almost every day from 2003 to 2006, there seemed to be a new Support ticket on this topic in our inbound queues most times of the day.

I am a Software Engineer with IBM’s Lotus Technical Support, serving on the Notes/Domino Application Development team for the past seven years. Our team supports all things Domino Designer, including the Out of Office Agent (currently ½ of the Out of Office Feature).

In supporting the Out of Office Feature back then, I also noticed that we kept receiving the same types of calls daily, and I wondered: “What is so complex about this feature?  Why has this topic been our team’s #1 call generator, every month for (at least) six years now (factoring in the infinite combinations of design elements available for custom database design)”?

Digging for answers

In my quest for answers, I dove in headfirst and found many dependencies—not all of them agent related—that are required to make this innocuous-looking client menu option work properly.

The complexity of the feature multiplied exponentially with the introduction of Lotus iNotes (release 5.0.5) and then again with Notes client-side editor-level access through AdminP (release 6.0).

Out of the 150+ Support Technotes/Techdocs I found on the Out of Office feature back then, none of them addressed how it really worked, end-to-end, nor its configuration requirements.

Sharing the knowledge

The results of my research include the four-part Techdoc series, Guide to the Notes/Domino Out of Office, an FAQ Technote, an internal Knowledge Collection Technote, and a customer-facing Webcast on Troubleshooting the OOO Feature (delivered May 2008).

In response to numerous requests, the aim of this article is to dive deeper into the ND8 Out of Office service, supplementing the information in last year’s developerWorks article, "The new IBM Lotus Notes 8 Out of Office functionality," in addition to the above-mentioned Webcast.

Defining our terms

First, note that when discussing the Out of Office service, it is almost impossible to avoid discussion of the Out of Office agent (OOA). For the purposes of this article, these and related acronyms are defined follows:

• OOA = Out of Office Agent
• OOS = Out of Office Service
• OOO = General discussion of the Out of Office feature, which could include both OOA and OOS
• trong>OOOProfile = The Out of Office Profile doc associated with the OOO feature.

 
Upgrading to Notes/Domino 8.x and the OOS

Let’s start by highlighting some of the key Notes/Domino 8.x OOS features cited in the “The new IBM Lotus Notes 8 Out of Office functionality” developerWorks article (for a complete list of features, please refer to the Notes/Domino 8 Reviewers Guide and to the article itself):

• Delegates/admins may now enable the OOO (both OOS and OOA) for another user
<
• As with OOA, it requires Editor+ access to the mail file
• OOS supports failover (OOA does not)
• OOS mail notifications are immediate (instead of every 6 hours by default, for the OOA)
<
• OOS supports a minimum absence of 1 hour (vs. 1 day for OOA), represented in the Client UI as the “Specify Hours” section of the OOOProfile (“ShowHours field)
• OOS is automatically disabled for you on the return date/time
• OOO Type is now set in the Domino Server Configuration document, via the Router/SMTP tab > Advanced > Controls > “Out of Office Type” field

  When upgrading your Domino servers to version 8.x, you must satisfy the following criteria, to successfully configure and use the OOS:

• All elements (client, server, mail template) must be 8.x, with no exceptions.
• After saving the change to the Mail Configuration doc, you must restart the Domino server. Restarting just the router task is not enough. (Trust me on this: I tried to find ANY way to not have to reboot Domino.)
• If one of the elements is not version 8.x, then the functionality defaults back to the Out of Office Agent (OOA), again, with no exceptions.
• If servers are clustered:
• All servers should be at 8.x in order for the service to be enabled: Remember that the OOS does fail over in a cluster if one server goes down, but only if all servers in the cluster are 8.x.
• OOS must be selected in ALL Mail Config documents for the service to function properly in the domain.
• If you have a universal Mail Config document for the entire domain, and you have individual Mail Config docs as well, all the individual Config docs must be set to the “Service” (OOS) type in order for the service to be used successfully within the domain.

Thus, in a mixed and clustered environment, you must pay careful attention to the Configuration documents. If you want to use the OOS, but one server is 6.x or 7.x and the other is 8.x, the OOS may not enable and run successfully.


Once you’ve selected the OOS and restarted the Domino server, the Notes or DWA client must be able to establish a connection with the Domino server (the first time), so as to determine which Out of Office type to use.

For example, if you are enabling for the first time from an Island (Disconnected) location, you will not be able to use the OOS. You ma y set/enable the OOS from a local replica, but again, there must be a connection to the Domin o server in order to realize the service setting. If the Domino server cannot be reached, the error message in figure 1 displays.

Figure 1. Error w hen server cannot be reached

Once the connection is established, PostOpen LotusScript code in the OOOProfile form executes to store the detected value in the “TaskType” field of the OOOProfile.

A TaskType field value of “1” indicates the OOA will be used, while a value of “2” indicates the OOS will be used. It is actually only necessary to connect to the Domino 8.x server once, to pull this value down to the profile, assuming that the Profile document is not overwritten or deleted. Subsequent runs after that result in using the same/previous Out of Office TaskType.

Some upgrade issues and/or oddities to be aware of

The good news is that there have been far fewer issues and Support-reported calls with the OOS than with the OOA. I find that the OOS is quite easy to configure, set up, and debug, and it seems that there is far less confusion about what it does and how it works now. Nevertheless, here are some issues worth noting:

A.  Profile Data is cached, not refreshed immediately (in some cases):

One minor occurrence I have seen and worked with (I call it an “occurrence” and not a bug, because it is not reproducible on demand and is usually resolved before we can test for reproducibility) is a caching issue, typical of all Notes/Domino Profile documents.

Assuming the server has been configured to use the OOS, the first time a user opens the OOO in a Notes 8.x client and attempts to enable the service, the ShowHours field does not display in the Notes client as it should. This is primarily due to the previous profile data being cached in the client.

WORKAROUND: If you simply restart the Notes client OR update the browser cache to refresh “on every visit to the page” (for DWA), the ShowHours field typically displays as expected.

B.  ShowHours field not displaying in either the Domino Web Access (DWA) or Notes client

I stated “…typically displays” in the “workaround” sentence above because there has been one OOS issue that’s been reported, but it is neither easily reproducible nor consistent:

With all the elements at the 8.x level, the service selected, and the Domino server rebooted, the ShowHours field indicative of the OOS does not display in one client or the other. In three of the four servers in which I’ve witnessed this (none of them my own test machines), the Notes client could enable the OOS, while the DWA client for the same user, same server, and same mail file would enable the OOA, or vice versa.

Further, the ShowHours field was missing every time upon opening the OOO Profile document in DWA, whic h was how we knew that OOS would not enable in these cases.  This was occurring for new and upgraded mail files alike, mail file owners and delegates.  

NOTE:  Reliably, if you see the ShowHours field in the current client, you will enable the OOS, and if you do not see the field, then you will enable the OOA.

Again, the symptoms seemed to point to a caching “discrepancy” because we know that, even though the same OOO Profile document is used, the profile data is cached uniquely in the browser vs. the Notes client. This is why, if you enable the OOO feature in the Notes client and immediately open your DWA client, the OOO status will reflect “Disabled,” even though either the service or agent is already enabled and running as expected—because it was set by the other client.

NOTE:  The browser’s cache is not the same as the Notes client cache.ndk file, and these files do not currently have a way communicate with each other. This is the only logical explana tion for why one client type does not always reflect the same OOO status as the other. Understandably, this has been very confusing and troubling to many end users over the years.

In addition, in one of the four cases I’ve worked, we saw the opposite e ffect; that is, the DWA client UI displayed the ShowHours field and enabled the OOS, while the Notes client UI did not show the field, and, in turn, enabled the OOA.

WORKAROUND: One possible workaround is to enable and disable the OOS in the (same) client that will allow it. For example, let’s say it’s the Notes 8.x client; the next time you go into the other (DWA) client, the ShowHours field should display and then allow you to enable the OOS in the DWA client. DWA appears to recognize that the mail file will run the OOS (not agent), but only when OOO is in a “disabled” state. This issue has been reported to Quality Engineering via SPR# LMAN7HPP3L.

If the ShowHours field does not display in the DWA client but does display in the Notes client, remember to check the Internet options for the browser cache, and if it is not already configured, set it to “refresh on every visit to the page.”  To test further, try opening the same mail file from a different browser and workstation.

In one case, we found that the ShowHours appeared once but then disappeared from the clients. This was directly related to the fact that one of the servers in the cluster was still 7.x (using the agent), and the user was currently connected to the Domino 7.x server instead of the primary home/mail server, which was 8.0.2.

Because one of the servers in the cluster was 7.x, only the OOA could be enabled within that configuration. Thus, it is always a good idea to exhaustively check all the Configuration documents in the domain, to ensur e continuity across all mail servers.

The other three issues we’ve seen occur only for the OOA:

• After upgrading from 7.x to 8.x, if the OOA is on at the time that the convert task is run to upgrade the user’s mail file to mail8.ntf, the OOA will reply once to every message, not just once to each sender, as it always had. The issue is being tracked in SPR# CTSI7HBP34, and currently there are no plans to address it. (This was originally intended as a feature option, but it was pulled before Notes/Domino 8.0 became generally available.
• In mail files in which editor-level users have enabled/disabled the OOA at least once on the 8.x server with a 7.x mail template design, executing the convert task to upgrade the design from 7.x to 8.x will enable the OOA. In order for this to occur, the OOA would also need the checkmark5 icon associated with it. This issue is documented in SPR# PALT7FGMAD and Technote# 1307609, and is expected to be resolved in Notes 8.0.3 and 8.5. The current workaround is to manually disable the enabled agents (after the fact), or delete the OOA from the suspected mail files and refresh the design, before running the mail conversion utility.
• Similarly, we have found that upon upgra ding from 8.0.1 to 8.0.2, the Design task enables the OOA for editor-level users. This issu e is documented in SPR # PALT7JBPEQ and is currently under investigation.

FAQs and some not-so-trivial “trivia” about the OOS

Q.  I have just upgraded my Domino server to 8.x, but only some users have been fully upgraded to 8.x. If I enable the OOS in my Configuration doc, what will happen for those users not currently using mail8.ntf or the Notes8 client? (DWA users need only the 8.x server and mail8.ntf.)

A.   Since the OOS requires that the client, server, and mail template all be at version 8.x, the OOA will be used in those mail f iles where one of the elements is not 8.x. The OOS does not get triggered, or kick ed off, or throw any errors.

The OOS never even gets a chance to kick off because the TaskType field, only available with the 8.x version of the OOOProfile form, is not available. The TaskType field value indicates which piece of the Out of Office feature to enable: “1” for the OOAgent, and “2” for the OOService.

Another important field to note is the TaskState field, also only available in the 8.x version of the OOOProfile form of the mail8.ntf. A TaskState value of “0” indicates an OOO status (either OOA or OOS as determined by the TaskType) of “Disabled” (or “Off”), and “1” indicates “Enabled” (or “On”).

Q.  Besides the server command “tell router o,” what are the other ways I can tell whether the OOS will be used instead of the OOA?

A.   (1) The ShowHours field: It displays in the Notes 8.x client and DWA UI only for the OOS; hides for the OOA because the hourly interval is not available to the OOA. If you see the section highlighted in red in figure 2, the OOS will be enabled when the user clicks the “Enable and Close” button.

Figure 2. Specify hours section

Domino Administrator Client: There is a new column in the Files tab of the Domino Administrator client that shows which users are running the OOS (see figure 3).

Figure 3. Files tab

 

Mail Message Document Properties: The OOO mail notification message field “GeneratedBy is set to “OOService” (see figure 4) instead of “OOAgent” (see figure 5).

Figure 4. OOService email body (also with GeneratedBy field)

 

Figure 5. OOAgent email body (also with GeneratedBy field)

Font size and style: The OOO mail notification body field font is slightly different between OOA and OOS. (You can vaguely see in figures 4 and 5 that the font text in the OOService email is slightly bolder and larger than that of the OOAgent.)

Q.  I disabled my OOS manually, early. Why does my database still show in the “tell router o” list?

A.   The OOS does not function like the OOA in that it processes messages only when they are received. If you manually disable the OOService, the mail file is still detected by the r outer until the next incoming message is received and delivered to that mail database. This new mail will, in essence, “kick” the mail file out of the router’s OOS.

In other words, if you want to remove a mail database from the router’s server after it was prematurely disabled, send a test message to that mail database to facilitate its removal from the OOS queue. If, however, no mail is received, the mail file is removed at the 4AM maintenance.

Q.  How/why is the OOS more efficient than the OOA?

 

A.   In general, running an agent requires more ser ver resources than running a service. (It would be impossible to provide performance data for all systems because each environment has unique hardware, software, processing speeds, and Domino server configurations—including varying threads of each Domino server task and process, memory allocation, 32 vs. 64-bit, etc.)

 

The router task gets a handle to an incoming message and generates the OOO notification to its recipient at the same time it is processing the newly received message to be delivered to the recipient’s mail inbox. This is more efficient because the server already has the handle to this newly received document, as opposed to handling the mail routing, then later getting the handle to the same document after delivery.

 

When the OOA is used, server source code executes to see if this agent is to be queued in the amgr queue and checks the security of the agent signer; if it all passes validation, then it is queued into amgr.

 

The agent kicks off, loads the necessary script libraries into memory, and runs the LotusScript code on a secondary layer of the API. The LotusScript code gets a handle to all messages in the database the first time it runs, determines which ones to act on, processes each message one at a time, generates a new mail message as needed, and sends it to the mail/box for router to process and deliver it, marks internal flags on each of the documents as processed, moves to the next document….you see where this is going.

 

Thus, there is source code plus LotusScript agent code that executes when an agent is loaded, queued, and executed. In contrast, the OOS executes only Domino server source code that generates the new OOO mail notification, while it has a handle to the original message, and then delivers the original message. This is also why the OOS mail notifications are (almost) instantaneous.

 

Q.  What is the OOServiceProfile used for? How is it different from the OutOfOfficeProfile document?

 

A.   The OutOfOfficeProfile document is used for both OOA and OOS. It (still) stores the dates you will be out, a list of email addresses of people that were notified from the OOA (“Notified” field), and all other UI data for both the OOA and OOS, just as it always has. The new OOServiceProfile document stores the list of the people notified by the OOS in the fields Notified_servername1 and Notified_servername2 respectively.

  < /strong>

Q .    We have previously used debug_amgr=* to troubleshoot the OOA. Is there something similar to use to debug the OOS?

 

A.  Yes. Debug_OOS=1 logs detailed output to the Mail Routing event log about the output of each step, each user, and status. (At this point, it would be a fine time to insert a lovely screen shot of the type of output returned from a specific OOS issue, but I have been unable to track any real issue with the OOS, which, I feel, is a really good thing!)

 

Q.  The OOA, as well as all agents, are unable to fail over in a clustered environment.  The OOS does fail over. How does this work?

 

A.  In a clustered environment, the router marks a received mail message with the field $OOS. There is router code to prevent re-processing of documents marked with this field.

 

Q.  How does the Delivery Options checkbox “Do not notify me if recipient(s) are out of the office” work?

 

A.  When you check this box (the field RecNoOutOfOffice) on the Delivery Options of the mail message to be sent out, the email is marked with a new field flag ($AutoForward), set to a value of “1.” In essence, this $AutoForward field tells the recipient’s side not to respond to that email if the OOO feature is enabled in the recipient’s mail file.

 

There is no limit to the amount of OOO notifications that the $AutoForwa rd would “block.” I have not located any issue with this feature or any changes in behavior since its introduction, which I believe was in R5. (However, I was unable to locate an R4 design to verify.)  The RecNoOutOfOffice field can be found on the “(Delivery Options)” subform of the mail template.

 

Q. As the OOS is executed by the router, when does it execute in relation to, say, the Domino mail rules?

 

A.   The order of execution of events in the router task is as follows:

 

ROUTER:

1.  Domino (server) mail rules

2.  Client mail rules

3.  ‘Before new mail arrives’ agents

4.  Out of Office service

5.  Mail is delivered to the user’s inbox

POST-ROUTER:

6.  (If enabled) Out of Office agent (at specified interval after mail is delivered)

Q.  If I send a test message to myself, will the OOS reply to it?

A.   No. It will also not respond to mail that was automatically generated.

Q.  In Notes/Domino 8, if I enable the OOS for another user, what name will be in the “From” field of the automated re plies?

 

A.   If you enable the OOO feature for another user (OOA or OOS), the name in the From field of the automated replies is the Mail file “Owner” as specified in the Calendar Profile doc.

 

With the OOA prior to version 8.0, the user id file that signed the agent (clicked the enable button in the client UI) was the name in the “From” field of the automated reply messages.  To further ensure this would occur, a Hide/When formula was added to the 6.x and 7.x code streams that would hide the OOO option for all but the mail file owner.

 

In 8.x, the option only hides for users who have author access or below. As a result, an administrator or delegate may easily set/enable the OOO feature (either agent or service) for another user.

 

Conclusion

In summary, the Out of Office Service (OOS) feature is simple to configure, set up, use, and troubleshoot. Within the first year of its life, I am happy to report that we have seen no major, reproducible issues with it. I hope that you will enjoy using the feature as much as I have, and that it has been worth the wait!

 

Acknowledgments

The author wants to especially thank Julie Kadashevich, Feature Developer for the Notes/Domino Out of Office feature for many years; Tarcio Constant, current feature developer for the client-side OOO; and Lisa Mallahan, QE in this area.

 

Julie was instrumental in passing on the majority of the knowledge to Technical Support. She was always responsive and available to answer all our questions while she was the Feature Developer for this area, and even afterward. Tarcio and Lisa have taken over this post and are similarly diligent in responding to a myriad of questions and requests for tests, and in providing much support to Amy and her team in so many ways.

 

Resources

• The new IBM Lotus Notes 8 Out of Office Functionality

 

• Webcast:  Troubleshooting the Notes/Domino OOO Feature

 

• Lotus Notes Out of Office Agent Revisited, Part 1 & Part 2

 

• ND8 Reviewers Guide

 

• Guide to the Notes/Domino Out of Office Agent, Parts 1-4

 

• Frequently asked Questions (FAQ) for the Notes/Domino Out of office Functionality

 

 

About the author

Amy Knox has been a Level 2 Support Engineer with IBM Lotus Support since May 2000. She worked on the Notes Client team for her first year before moving to the Notes/Domino Application Development team, serving as the Team Lead of the App Dev team from 2005 to 2007.

 

Before beginning her career at IBM, she acquired a Master’s degree in Hispanic Literature, specializing in 20^th Century South American poetry and Post-Modern novel. She believes that her effectiveness in learning spoken languages (four so far) has been a direct catalyst for learning programming languages.