Lotus Notes Out of Office Agent, revisited: Part 1

Out of Office agent basics

The Lotus Notes Out of Office agent is one of the most widely-used and useful agents in Notes. In this first of a two-part article series, we take a detailed look at how the agent works and how you can customize it.

Share:

Julie Kadashevich, Software Engineer, EMC

Julie Kadashevich has been working as a developer on the programmability team of Domino server since 1997. Her specific area of expertise has to do with anything related to agents.


developerWorks Contributing author
        level

20 September 2005

Also available in Japanese

In this two-part article series, we will take an updated look at the Lotus Notes/Domino Out of Office agent. In 1998, we published an article called “Demystifying the Out of Office agent.” Although this article has remained well-read over the years (and is still applicable to users running Notes/Domino releases 4.5 and 5.x), many things have changed since we published it. This new article series will revisit the Out of Office functionality in Notes/Domino 6.x and 7.0. In part 1 of this series, we start with an introduction to the Out of Office agent, and examine the major differences involved in how the agent is enabled. In part 2, we examine common configuration questions about the Out of Office agent, and discuss troubleshooting techniques.

This article is intended for Notes users who want to start using the Out of Office agent, and administrators who want to help their Notes users run this agent.

An introduction to the Out of Office agent

The Out of Office agent is a LotusScript agent that is part of the Notes mail template. When enabled, the Out of Office agent automatically responds to mail that arrives when you are out of the office. When configuring the agent, you can specify the text of the message, and set rules regarding who should not receive any messages, or who should receive a special message. The Out of Office agent can mark your calendar “busy” for the time you are away if you so choose. The agent generates automatic responses once for each person who sends mail to you, even if the person sends several messages to you during your absence.

Configuring and enabling the Out of Office agent

To enable the Out of Office agent, open your mail database, click Tools, and select Out of Office. Alternately, you can select Actions - Tools - Out of Office. You can also enable the agent from your Calendar by clicking Tools and selecting Out of Office. Finally, you can enable the Out of Office agent when using Domino Web Access via Tools - Out of Office.

When you select Out of Office, you will be presented with a tabbed dialog that allows you to configure the Out of Office agent (see figure 1).

Figure 1. Out of Office dialog
Out of Office dialog

The Dates tab is the only one that contains required data. Use this tab to enter the dates when you will be out of the office. These dates will be included in the text of your messages as the dates when you are unavailable. The agent will continue to run until you turn it off. On the day you return, the agent sends you a "Welcome back" message with the list of people to whom messages were sent, as well as a reminder to you to turn the agent off.

The next three tabs of the Out of Office dialog are optional. They contain the text of the message to be sent, an alternate message for a special set of people, and an exceptions list (people who should not get a notification that you are out of the office). If you don’t need to change these defaults, you can click the Enable button on the Dates tab to enable the Out of Office Agent. The Out of Office dialog then shows the current status as Enabled.

Let's take a quick look at the optional tabs of the dialog. The second tab, Out of Office Message, allows you to add the text that you want to appear in your email response (see figure 2):

Figure 2. Out of Office Message tab
Out of Office Message tab

The third tab, Special Message, allows you to send a special message to people listed on this tab (see figure 3):

Figure 3. Special Message tab
Special Message tab

And the fourth tab, Exceptions, allows you to specify who should not get an automated response (see figure 4).

Figure 4. Exceptions tab
Exceptions tab

If a group name is entered into any of the fields, the group will be expanded into individual members. This is done for efficiency, so that this time-consuming operation is not performed on the server every time a message needs to be processed. The side effect of this expansion is that the information about group membership is not preserved. If the group membership changes at some later time, this change will not be reflected in the Out of Office agent unless the group name is re-entered and re-expanded.

One final note: As mentioned earlier, you can use the Out of Office agent in Domino Web Access. The configuration steps are similar to those we've just described for Notes, although the interface is somewhat different (see figure 5).

Figure 5. Enabling the Out of Office agent in Domino Web Access
Enabling the Out of Office agent in Domino Web Access

What does the Out of Office agent not do?

The Out of Office agent does not support delegation. (We discuss how to turn on the agent for someone else in part 2 of this article series.) Also, the Out of Office agent does not work for users with Author-level access. In addition, the Out of Office agent does not notify the sender for each and every email they send, just the first one. (This is by design.)

Where and when does the Out of Office agent run?

The Out of Office agent automatically determines the home mail server of the user, and enables the agent to run on that server. (See the sidebar.) By default, the agent runs every six hours, between 4 AM and 12 AM. (The agent will not run between 12 AM and 4 AM, because many other maintenance tasks are run during this time). To change the frequency of how often the agent runs, see the section “Customizing the Out of Office agent” later in this article.

Home mail server

Your home mail server is the server where the router deposits mail (as opposed to the other servers that may contain a replica of your mail file). Your administrator specifies your home mail server in your Person document in the Domino Directory, and you also can see it in your current Location document. (Choose File - Mobile - Edit Current Location, and look in the Home/mail server field on the Server tab.) The Out of Office agent itself will automatically select the home/mail server defined in your current Location document.

What rights does the user need to run the Out of Office agent?

Domino agents are controlled by database ACL rights and programmability restrictions. The user’s ACL, defined for each database, dictates which changes the user can make in that database (such as read, write, and modify documents; create and modify agents, and so on). Programmability restrictions are defined in the Domino Directory's Security tab, and control who can execute agents on the server, and whether the user’s level of rights allows that user to use methods that can affect security. The restricted level of rights required by the Out of Office agent does not allow the user to perform any methods that impact security.

Prior to Notes/Domino 6, to run the Out of Office agent, a user needed at least Designer access to the mail file, as well as the ACL right to create LotusScript/Java agents. Users also needed the rights to run LotusScript agents on the server.

Starting with Release 6, users with Editor access to their mail databases are also able to run the Out of Office agent. The Editor level users do not need to have rights to run LotusScript/Java agents on the server, but their agents have to be provisioned to be run by them by either the AdminP process or by an administrator. An Editor level user needs to have Author access to the Administration Requests database (Admin4.nsf), because the request will be submitted on their behalf. The default access on the Admin4.nsf database is author; no special configuration is required if defaults are not changed.

We provide more details for configuring Editor level users in part 2 of this article series.


Customizing the Out of Office agent

As we mentioned previously, the Out of Office agent is a LotusScript agent that resides in the mail template. The name of this agent is OutOfOffice. You can see it in the agent list in Domino Designer (see figure 6).

Figure 6. OutOfOffice agent
OutOfOffice agent

If you have Designer or Manager rights to your mail file, you can modify this agent by double-clicking it in the agent list. You can change when the agent runs, what server it runs on, and whether or not it runs on weekends. Some advanced users have been known to modify the logic of the agent to further customize it to their needs. You can change the schedule as well as the server name on which the agent runs by clicking the Schedule button on the first tab of the Agent Properties box (see figure 7).

Figure 7. Agent Properties
Agent Properties

Here are a few things to keep in mind if you change the agent:

  • Always make a backup of your database before you make changes. Anyone can make a mistake, and a backup gives you the ability to back out of all changes.
  • If you are making changes to the template, you will propagate your changes to all users on your Domino server(s).
  • If you change the agent to run more frequently than the default (every six hours, or four times a day), be aware that you will be putting slightly higher load on the server.
  • If you choose the "Any server" option to run the agent on, and your mail file has copies on more than one server, the agent will run on more than one server and each message may be processed more than once. That means more than one notification may be sent for each mail you receive.
  • If you change the agent trigger to “before mail arrives,” the agent will not work. The "before mail arrives" trigger does not populate the UnprocessedDocuments property used by this agent’s logic.
  • If you change the agent trigger to “after mail arrives,” the agent will run on your home mail server (ignoring the “server to run on” setting). Again, be aware that you will be putting slightly higher load on the server.
  • If you select Local as the server to run on, you need to make sure that you select the "Enable scheduled local agents" option (under File - Preferences - User Preferences) and that your mail replicates to your local machine. (For Editor level users running the Out of Office agent on a local replica, see part 2 of this article series.)
  • If you are making complex changes (for example, changing the code of the agent), it may be difficult or impossible for IBM Support to help you with any problems without backing out of the changes you made.
  • When a new release of the template comes out, the template will be automatically updated by the Design task (unless you select "Prohibit Design Refresh or Replace to Modify"). You will need to re-integrate your changes into future versions of the mail template, so keep a backup of your changes.

The Out of Office agent in the clustered environment

The Out of Office agent runs on any and all servers on which it is enabled. Typically, you want this agent to run on only one server to avoid sending out multiple acknowledgements for the same message. If you enable the agent on one server, and it fails over to a replica where the agent is not enabled, the agent will not run on the second server. When the first server becomes available again, the agent will catch up, and process all the documents that it might have missed while the server was unavailable. If users are receiving multiple notifications for the same message, see the Troubleshooting section in part 2 of this article series.


Differences between enabling the Out of Office agent by Managers/Designer and Editors

In general, when everything works correctly, the user does not need to know about the differences between different access levels and does not need to do anything special when they enable the agent. The discussion in this section is only aimed to assist troubleshooting when something goes wrong.

How the agent is enabled for Designers/Managers compared to how it is enabled for Editors is different because Editor level users do not have the rights to modify agents. Enabling the agent consists of two parts: signing the agent, and making it eligible to run on a schedule. Signing the agent changes its design, and Designer/Manager access is needed to do this.

To make it possible for Editor level users to enable specially designated agents, we separated the two parts of enabling the agent by allowing the agent to become eligible to run without resigning it. We also needed a way to specify on whose behalf the agent is running (because, in this special case, we don’t want to use the signature as a way to determine the identity of the effective user of the agent). To facilitate this functionality, we created two new agents properties. The “Run on behalf of” field contains the name of the user on whose behalf the agent will run (the Editor level mail owner). The “Allow user activation” checkbox, when enabled, allows Editor level users to enable and disable the agent (see figure 8):

Figure 8. New Agent properties
New Agent properties

Any server agent can be designated to be "activatable" by a user with Editor access. But only users with special privileges are allowed to set up this configuration. This special privilege is defined in the Server document's Security tab, and is called the “Right to sign agents that run on behalf of others." This is a high level of privilege and should be given out carefully. (The server has this privilege implicitly.)

Editor level users do not need rights to run LotusScript or Java agents, because they do not sign the agent. The agent will run because it was signed by the ID that provisioned the agent to run on behalf of the user, and any ID that has the right to sign agents that run on behalf of others (which is needed to for configuring this type of agent) has the right to run restricted LotusScript/Java agents.

Configuring the Out of Office agent to run for Editor level users

In most cases, for the Out of Office agent to work properly for an Editor level user, you do not need to configure any of the agent properties in the Basics or Security tabs, or grant an Editor level user any security rights in the Domino Directory Server document. The Notes client, in tandem with the AdminP task, performs all the proper configuration for you. The configuration for Editors is even simpler than for Designer and Manager level users; they require the Domino Directory Server document's Security tab to list them as individuals who can run LotusScript agents, and they require ACL rights to create LotusScript agents. The simplest scenario for Editor level users is when no changes are made to the template and the template's design elements still have the signature of "Lotus Notes Template Developers."

But if things do not go as expected, read this section to learn the details of what is required to enable the Out of Office agent, and how it can be configured in several different ways.

When the "Allow user activation" option is selected, Editor level users can enable and disable the agent. They are not able to edit it or even look at its content. If the flag is enabled and the mail owner has Designer or Manager level access, this flag has no effect. When "Allow user activation" is not selected (which is the default), the agent requires Designer/Manager level and rights to run LotusScript agents.

"Allow user activation" for Editor level users can be configured manually or programmatically. The Out of Office agent does this task programmatically by submitting a request to AdminP to configure and enable the agent the first time an Editor level user enables the Out of Office agent. If necessary, an administrator could set this initial configuration manually.

The programmatic approach uses the ConfigureMailAgent method, which creates an AdminP request “Set User name and Enable Agent.” AdminP sets the "Allow user activation" checkbox, populates the "Run on behalf of" field with the user name, and signs the agent with the server ID. See part 2 of this article series for more details on this topic.

To set up configuration manually, the person who is configuring this agent for the Editor level user should have Designer or Manager access to the user's mail file, and have the right to sign agents that run on behalf of others set in the Server document. To configure the agent, start Domino Designer, open the Agent properties box, and enter the abbreviated hierarchical name of the user into the "Run on behalf of" field. Then select the "Allow user activation" checkbox. The agent will be signed by the person who is configuring the agent.

In addition to configuring the agent to run for the Editor level user, the Out of Office agent needs to have the dates when the mail owner is out of the office (and any optional information, such as changes to the default away message). This information is stored in the Out of Office Profile document called (OutOfOfficeProfile). Creating or updating this document is done via the user running the Out of Office agent, or by running the (EditOfficeProfile) agent as described in part 2 of this article series.

If a manual configuration is done before the user selects Tools - Out of Office to specify the dates for the away period, when the user runs the agent, the agent will be enabled immediately. If a manual configuration is done after the user selects Tools - Out of Office (which then for some reason fails), the agent can be enabled by the administrator and it will start running and sending notices as specified by the end user.

After this initial configuration is performed (whether done manually or via AdminP), AdminP requests are no longer needed. The user can disable and enable the agent directly through Tools - Out of Office. Note that any time there's a change to the ACL (from Manager to Editor or vice-versa), the "user invocation" setting needs to be changed, so AdminP will run again the next time the user enables the Out of Office again.

Keep in mind that if a design update needs to update the agent’s design, the configuration information will be removed, and AdminP will be invoked again to configure the agent for the Editor level user. A design update of the agent occurs only if the code of the agent in the template has changed. Every time the agent is updated by the Design task, it stores the time stamp of the template agent in the agent in the actual database. The update happens only if the time stamp of the agent in the template is more recent than the stored time stamp from the previous update.

Figure 9 shows how the Out of Office agent appears in the agent list after it is disabled by the Editor level owner:

Figure 9. Out of Office agent disabled
Out of Office agent disabled

The "check-5" icon indicates that the agent will behave as enabled on R5 servers, but is disabled by Release 6 and later servers. See the discussion on compatibility of R5 and Release 6/7 Editor level access in part 2 of this series.

Figure 10 illustrates how the agent will look if the Editor level owner re-enables the agent (notice the icon next to the agent's name):

Figure 10. Out of Office agent re-enabled
Out of Office agent re-enabled

Note that the “last modified” shows the user name, rather than the server name, as it was the case during the initial enablement performed by AdminP. The agent is still signed by the server, and will run without a problem on the server. You can see the identity of the signer by looking at the bottom of the Design Properties Tools tab (see figure 11):

Figure 11. Signer field
Signer field

The following table compares the different methods for enabling the Out of Office agent (by someone with Designer/Manager access, automatically by someone with Editor access, manually by someone with Editor access, and via Domino Web Access.

-- Designer/ManagerEditor/AutomaticEditor/ManualDomino Web Access
Enabling performed byNotes ClientAdminP (first time),
Notes client (after first time)
Administrator (first time),
Notes client (after first time)
AdminP
Timing of enablingInstantWith delay (first time),
instant (after first time)
InstantWith delay (always)
Signature after agent is enabledMail file ownerServerAdministratorServer
"Run on behalf..." field after agent is enabledNot usedMail file owner nameMail file owner nameMail file owner name
Server restrictions for mail file ownerMail file owner needs restricted programmability rights.Mail file owner does not need to be given any rights.Mail file owner does not need to be given any rights.Mail file owner does not need to be given any rights.
Server restrictions for signerMail file owner and signer are the same, needs restricted programmability rights.Server does not have to be given any rights; the right is implicit.Administrator needs to have right to sign agents or run on behalf of someone else or right to run unrestricted methods.Server does not have to be given rights; the right is implicit.

Conclusion

In this article, we've introduced you to the Out of Office agent. We've explained what it does and how it works. We've also examined the major differences involved in how the agent is enabled.

In part 2 of this article series, we'll go into further detail about how to configure the Out of Office agent, and look at how to troubleshoot some potential issues you and your users may encounter.

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=94100
ArticleTitle=Lotus Notes Out of Office Agent, revisited: Part 1
publish-date=09202005