Demystifying the Out of Office agent

by
Julie Kadashevich
(with Barbara Burch)

Level: Beginner
Works with: Notes 4.5
Updated: 02-Nov-98

So, you're off on your big vacation, but don't want to leave your co-workers feeling stranded? If you're a Notes mail user, you can use the Out of Office agent to automatically respond to messages that you receive while you are out of the office. Your automatic response can say exactly when you will be out of the office and when you will return, plus any additional details that your co-workers may need to know (such as, who to contact in your absence, whether you'll be checking e-mail, and so on).

In this article, we will take a closer look at the Out of Office agent, and hopefully work on demystifying it for you. The article first includes an introduction to the Out of Office agent, including the steps for using it. Then, it answers some common questions about the Out of Office agent, including:

What kind of rights do you need for running the Out of Office agent?
Why would the Out of Office agent not run as expected?
How can you customize the Out of Office agent?
How does the Out of Office agent work in a clustered environment?
What is the performance impact of deploying Out of Office agents in a large organization?

This article is intended for Notes users who want to start using the Out of Office agent, and administrators who may want to help their Notes users with using the agent. For in-depth information on how the Out of Office agent works, see the commented code for the agent in the R4.x mail template. For more information on the common problems you may encounter when dealing with other agents, see the

Iris Today

article "

Troubleshooting agents

An introduction to the Out of Office agent

The Out of Office agent is a LotusScript agent that was first introduced as part of the Notes R4.5 mail template. You can enable the Out of Office agent to automatically respond to mail that arrives when you are out of the office. While you are gone, Notes sends a reply to each person who sends mail to you, saying that you are out of the office and indicating when you will return. To be efficient, Notes generates automatic responses only once for each person who sends mail to you, even if a person sends several messages to you. On your return date, Notes sends you a "Welcome Back" message that includes a list of all the people it sent messages to.

Enabling the Out of Office agent

Use the following steps to enable the Out of Office agent:

Verify that you have the appropriate rights in your mail database to enable the Out of Office agent. Choose File - Database - Access Control. Select your name, and make sure that you have at least Designer access with "Create LotusScript/Java agents" rights.

Note: You must also have access to run LotusScript agents on the server that contains your mail database. For more information on server access, see the "Common questions" section later in this article.
From within your Notes mail file, choose Actions - Mail Tools - Out of Office.
Enter the dates on which you are leaving and returning. (These are the dates during which the agent will operate, and by default, these dates will appear in the text of your message. The agent continues to run until you turn it off. On the day of your return, the agent sends out a "Welcome back" message, which reminds you to turn the agent off.)
(Optional) If you want to create your own automatic response message, in the box "My Out of the Office message for most people/groups," change the subject of the message or change the message itself.
(Optional) If you want to send a different message to one or more people, enter their names in the field "People/groups who should receive a special message." Then enter a subject and message in the box "My Out of the Office message for special people/groups."
(Optional) If there is anyone that you do not want to receive an automatic response, enter them in the field "People/groups who should not receive any messages."
Click "Enable Out of Office Agent."
When Notes prompts you to "Choose Server to Run On," choose your mail server, and then click OK. The default server is Local. However, in most cases, you should select your home mail server.

Note: 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 Public Address Book, 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). If necessary, you can select a mail server that has a replica of your mail file, or select Local if you replicate your mail to work remotely. In Notes R5, you will not have to specify the server for the agent to run on. The agent itself will automatically select the home/mail server defined in your current Location document.

By default, the Out of Office agent runs once a day at 1AM using a "daily" schedule trigger. When the agent runs, it first checks to see whether it is supposed to respond to mail that day, and if it is, it processes all new mail messages. It checks to see if the sender is in the special processing lists, checks to see if this person has already been notified, and then mails an appropriate message.

When you return to the office and want to stop the agent from running, choose Actions - Mail Tools - Out of Office, and click "I Have Returned to the Office."

Common questions about the Out of Office agent

This section answers your common questions about the Out of Office agent, including what kinds of rights you need for running the agent, why the agent might not run as expected, how you can customize the agent, how the agent works in a clustered environment, and what the performance impact might be when you deploy the agent in a large organization.

What kind of rights do you need for running the Out of Office agent?

As we mentioned earlier, to initially enable the Out of Office agent, you need to have at least Designer with "Create LotusScript/Java agents" rights in the ACL of your mail database.

When you enable the Out of Office agent, this action signs the agent with your signature. This means that the agent runs with your rights on the server. Server administrators control who can run agents on a server by using the Agent Manager section of the Server document:

Because the Out of Office agent is a LotusScript agent, you need to be listed in the "Run restricted LotusScript/Java agents" field. This allows you to run agents that have access to a large subset of LotusScript features, and is sufficient for most operations -- including those required for the Out of Office agent. (Restricted agents are not allowed to execute operations that may affect the overall security of the server, such as file I/O operations.) As shown in the screen above, many organizations that deploy the Out of Office agent use a wildcard setting (*/Acme) in the "Run restricted LotusScript/Java agents" field.

Why would the Out of Office agent not run as expected?

When the Out of Office agent doesn't run as expected, you should look into the following areas:

Did you specify the correct mail server for running the agent on? The default server is Local, which is only appropriate if you are replicating mail to your local machine. If you want to run the agent on the server, you need to specify your mail server. (As mentioned earlier, Notes R5 will automatically determine your mail server for you.)
Do you have the appropriate rights for running the agent on the server? Make sure that you have the appropriate rights in the ACL of your mail database, and that you are listed in the "Run restricted LotusScript/Java agents" field in the Agent Manager section of the Server document.
Did you know that automatic responses are sent only once to each sender, and that by default, the agent does not run on weekends?
Did you change the agent schedule/triggers? (See the following section for more information.)

How can you customize the Out of Office agent?

It may seem obvious, but the Out of Office agent is an agent, just like other agents. You can customize it by selecting the Agents list in your mail file, and double-clicking on the ProcessOutOfOffice agent. You can change its schedule, the server it runs on, whether it runs on weekends or not, and so forth.

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

If you change the schedule of the agent to run more frequently than the default of once a day, you are putting a slightly higher load on the server (see the "performance impact" section for more information).
If you select a server that is not your home mail server, you need to understand what that means. All new mail is delivered to your home mail server, and replicated to other servers. This means that the new mail will appear in your mail database on any server except your home server via replication, rather than by the router depositing mail into your mail database. This has a major impact for the "new mail" trigger type for this agent. "New mail" triggers, by default, run only on the home mail server. (Note that an administrator can change this default behavior. To allow "new mail" agents to run on any server, the server administrator can add the NOTES.INI setting, AMgr_DisableMailLookup=1. But be aware that depending on the logic of your agent, running the same agent on multiple servers may cause replication conflicts.) If the AMgr_DisableMailLookup variable is not set, and if the "new mail" agent is set to run on a non-home mail server, the agent will not run. In R4.62 and later, the following runtime error will be generated: "AMgr: Agent 'agent' will not run. It is intended to run on 'servername,'" where servername is the name of your home mail server.
If you select "Local" as the server, you need to make sure that you select the "Enable scheduled local agents" option (under File - Tools - User Preferences) and that your mail replicates to your local machine.

How does the Out of Office agent work in a clustered environment? If I enable the agent on one server in a cluster, and my mail fails over to another server in the cluster, what will happen?

The Out of Office agent runs on any and all servers on which it is enabled. Typically, you want this agent to run only on one server to avoid replication conflicts. 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.

What is the performance impact of deploying Out of Office agents in a large organization?

The performance impact of the Out of Office agent even in a large organization is negligible on the rest of the server performance. First, the agent is not active unless the users enable it. The percentage of people who are out of the office and have the agent enabled are usually relatively small. Second, the agent is relatively simple and does not do any heavy-duty processing. Finally, by default, the agent is scheduled to run at night so that it doesn't have any impact during the daytime period.

Conclusion

We hope this article demystified some aspects of the Out of Office agent, and helps you to put the agent to work for you. The agent should make it easier for you to keep up with your co-workers, even while you are out of the office.

ABOUT THE AUTHOR

Julie Kadashevich came to Iris in March of 1997 after working at FTP Software on Java and C++ mobile agent technology. She has been focusing on the Agent Manager as well as Java. Previously, she worked in the area of applied Artificial Intelligence at Wang Labs and received five patents in the field. She has Bachelor's and Master's degrees from Boston University, both in computer science. Outside of work, her new hobby is kayaking. She recently bought her own kayak and is working on taming it.