Where it begins: The home server

Users on the same home
server

Users in a different Notes domain

Users in other calendar domains

Related links:
Integrating C&S into a group application

C&S Administration LearningByte

Lotus Organizer

OfficeVision

Get the PDF:

(111Kb)

Calendar and scheduling was a long time coming to Notes, but when it appeared in Release 4.5, it was well worth the wait. The implementation took full advantage of the Notes architecture to support such key features as free time lookups, so that users who are scheduling meetings can easily check when their invitees are available to meet. In addition, new server tasks were added to manage a centralized database of free time data and to communicate with other calendar and scheduling applications, so that Notes users can check for free time in calendars kept in Lotus Organizer, or even in applications that run on other computing platforms, such as IBM's OfficeVision systems.

Occasionally, this distributed process of looking up free time can get out of whack. It's generally easy to see when there's a problem -- the free time lookups don't return any data. But because so much of the work is done automatically by server tasks, it can be hard to pinpoint the exact cause of a problem. While there are some things Notes users can do to troubleshoot a lookup problem, if multiple applications or multiple servers are involved, diagnosis and repair generally requires the intervention of a system administrator, because the primary diagnostic tools are server logs and console messages that users cannot access.

Fortunately, the most common problems have some common-sense solutions, say John Banks-Binici and Bruce Kahn, Iris developers who work on the calendar and scheduling functions.

Some of the common problems and their solutions include:

• Replication conflicts: If, for example, you are proposing a meeting and free time information for one of the invitees doesn't match what you know to be true -- if the boundary times (the beginning and end of the work day) or default busy times seem wrong -- it may be because the invitee's Calendar Profile has been overwritten as the result of a replication conflict. The fix is easy: The invitee can open the Calendar Profile, edit it to correctly set the defaults, and resave it.
• Connectivity problems: If, instead, you don't get any free time information back, or you get an "Information not available" message, you may have connectivity problems. Connectivity fans out from your home server, says Binici. The question is, at what point along the network connection hops from your client to your home server to the invitee's home server, did the lookup fail? A system administrator with access to log files and server console messages, can check to see how far the request got, identify at what point it failed, and isolate the server that broke the chain of communication. (If the request got to its destination, notes Binici, it usually gets back.)
• Access restrictions: If you receive a message that you do not have access to the free time information, the invitee most likely used settings in the Calendar Profile and Delegation Profile to restrict access to the information. Occasionally, access problems may also occur because a server somewhere along the connection chain doesn't grant privileges for you to connect to it. Server access is generally sorted out in the course of tracing the connection. Profile restrictions can be hard to pinpoint because users may not be aware of them, but some direct questions and answers usually solve the problem.
• Performance problems: If you don't get any free time information back for an invitee in another Notes domain, you may have performance problems. Lookups that cross domain boundaries are sent from your home server to the gateway server in the adjacent domain. If the gateway server is heavily loaded, says Binici, it may not respond quickly enough, and the home server will time out the request. This kind of performance problem is usually obvious because it affects not just one user, but many. The answer is for an administrator to set up a separate freetime gateway server to handle queries from outside the domain, and then to enter the name of that server in the CalendarServer field in the Domain document in the adjacent domain where the queries are originating.
• Dial-up usage: One other problem with an easy solution, according to Binici -- If you're trying to look up free time while running remotely, connected by a dial-up modem, stop. The free time lookup system simply isn't designed to support dial-up users; it's designed to be used over a connected network. (Notes Release 5 will make changes to the way dial-up connections are handled, which will improve this situation, says Binici.)

This article includes examples of these kinds of problems as a user named Tim Pennington tries to schedule a meeting, but cannot see the free time of Peter Miller, one of the invitees. Each of the other invitees represents a different type of connection and access -- a user who shares Tim Pennington's home server, a user on a different server, a user whose calendar is in Organizer, and a user whose calendar is on a mainframe. As connectivity fans out, the tools and techniques for troubleshooting vary.

The mechanics of Calendar and Scheduling
The calendar and scheduling features are implemented as functions in every Notes user's mail database. This ensures that these features are as widely available as possible. Mail and calendars are related in many ways. Just as most users need only one mailbox, they need only one calendar -- so the calendar appears as a view, along with the To Do view, in the Notes mail database.

There are some settings that govern the calendar's appearance and defaults for the available free time, as well as two different levels of access to the calendar data. These settings are accessible in a Calendar Profile document in your mail file. To open your Calendar Profile, choose Actions - Calendar Tools - Calendar Profile. The Calendar Profile document looks like this:



The Freetime Options section (shown in more detail below) lets you select who may perform free time lookups against your calendar data. You can allow anyone to do lookups. Or, you can deny access even to this level of information. (In any case, a lookup doesn't return any information contained in the calendar that might be sensitive. It returns only the fact that the calendar owner is either busy, or not busy for certain times.)

The button labeled "Allow other users to view your calendar" brings up a related document, the Delegation Profile. In this document, you can specify other users who may use the mail file, and you can share access to the calendar data. You can select who may read the calendar, and who may manage it. You may decide to give your assistant the ability to add and delete items in the calendar, for example, and all the people in your department the ability to read it. Or, you may set access so that only you can see the contents.

The real work of managing calendars and performing free time lookups is done on your home server. Two server tasks were added to Release 4.5: the Schedule Manager task and the CalendarConnector task. The Schedule Manager task creates and manages a centralized database called BUSYTIME.NSF that holds busy and free time data collected from all the mail files on the server and for resources, such as conference rooms and overhead projectors, identified in the server's Public Address Book. The CalendarConnector task handles communication with free time servers in the same Notes domain, in other Notes domains, and in other calendar applications -- including Lotus Organizer, IBM OfficeVision (also known as PROFS), and Time and Place -- so that scheduling can work both across Notes domains and across platforms.

Notes uses its Remote Procedure Call protocols to off-load lookups from the client to the server. The lookup is handled by a process on your home server. You first create a meeting request by creating a new calendar entry. The form includes fields for selecting the type of entry and filling in the details. The entry type is set to "Invitation" in the screen shown below, so fields are available for listing the invitees. Clicking the Find Free Time button sets the lookup process in motion.



Where it begins: The home server
Notes user Tim Pennington is trying to schedule a meeting with five people. When he clicks "Find Free Time," Notes first tries to find the users' names in Tim's Personal Address Book, and converts the ones it finds into fully qualified names. (The client can't convert group names.) Then, it sends the entire list of names to Tim's home server, Ajax. A process running on Ajax handles the request in several steps:

1. It first checks to see if any of the names are group names, and expands them if necessary.
2. It converts the names of users -- both the ones not found in Tim's Personal Address Book, and users found on group lists -- to fully qualified names.
3. It attempts to find the free time for all of these users locally, and returns any information that it finds.
4. Any users on the list who do not have their free time saved on Ajax are looked up in the server's Public Address Book to find their home server, and a request is sent to this server.

If there is more than one user on a server, the requests for that server are bundled together for efficiency. All requests and responses are returned to Tim in an asynchronous manner, depending on which servers respond the fastest. Tim's own home server will always return results first for the people who also share his home server.

The results of the lookup are displayed in the screen below. The results indicate that four of the invitees are free for the hour Tim wants to schedule -- but the free time data for one of the invitees, Peter Miller, is missing. The question is why, and the potential causes and solutions can be illustrated by using each of the other four invitees as examples.



Users on the same home server
Tim's home server, Ajax, is also Scott Bohannan's home server, so his free time information is retrieved and returned to Tim's client first. If Peter Miller's mail file were also on Ajax, his free time data might be missing or incorrect for one of these reasons:

• Peter has restricted access to his free time information in his Calendar Profile and has not included Tim on the list of users who can view the busy time data.
• Peter's Calendar Profile reports incorrect boundary times because it was overwritten by a replication conflict.
• In Peter's Person document in the Public Address Book, his mail file information is missing or incorrectly specified. If either entry is wrong, the Schedule Manager task on Ajax will be unable to retrieve and update Peter's free time data.
• The domain listed in the CalendarDomain field in Peter's Person document does not match the Notes domain for Ajax. In this case, the Schedule Manager will not monitor Peter's mail file for calendar data. (If the CalendarDomain field were empty, the Schedule Manager would treat it as if it matched the local Domain name, which in this case would be Ajax's domain.)
• And, in a very rare case, if Peter is on the same server, but does not have a Calendar Profile and no calendar entries, then the Schedule Manager will not monitor his mail file for activity, and there will be no data that it can present other users. If this should change (that is, if Peter adds any calendar entries), the Schedule Manager will detect this new entry and then display information for Peter to other users.

Troubleshooting same-domain problems
If Tim suspects that Peter Miller also uses the Ajax server or another server in the same domain as Ajax, then the easiest place to start troubleshooting the problem of Peter's missing free time data is with Peter Miller:
1. Peter should check his Calendar Profile (by choosing Actions - Calendar Tools - Calendar Profile) to see whether he has inadvertently restricted access to his free time information. If the "Only the following users can read my Freetime Schedule" field in the Freetime Options section includes specific users that are allowed access, then Tim's name must also appear in the field. (If the field is blank, access defaults to all, so that anyone can see the information in a lookup.)
   
   
2. Peter should also check this section of the Calendar Profile for the settings for allowable free times, correct them if necessary, and resave the profile. Occasionally users running older releases of Notes who replicate their mail file will find that these default boundary times have been overwritten by a replication conflict. (This is most often the result of a bug that allowed older versions of the profile to overwrite newer ones when a user's mail was replicated. It was fixed in Release 4.61.)
3. In his Person document in the Ajax Public Address Book, Peter should check the Home Server field. If the server name is incorrect, or his mail file information is missing or incorrectly specified, the Schedule Manager will not scan his mail file on Ajax for any data, nor will it monitor it for any changes.
4. Also in the Person document, Peter should check the CalendarDomain field to make sure it either contains the same name as Ajax's domain, or is blank. If it contains a domain name different from Ajax's (as it might if Peter had once kept his calendar in another application, or his mail file was formerly in another Notes domain), the Schedule Manager will not monitor Peter's mail file for calendar data.

Note that if the CalendarDomain field in the Person document is blank, the Schedule Manager task will read the Home Server field, and monitor that person's mail file for calendar data. The defaults for the Calendar Profile and Person document assume that a user with a valid Notes mail file is using the Notes calendar and making free time information available without restrictions.

This means that users who aren't even checking their Notes calendars and have never set up their Calendar Profile will be reported as having free time in lookups -- the results screen will display a white bar, not a gray one.

Using administration tools for troubleshooting
Notes users like Tim and Peter may be able to resolve the problem by trial and error, editing documents and resubmitting lookup requests. But if a server administrator is involved, the administrator has some tools available that may speed up the process.

1. First, the administrator can go to the Ajax server console and enter the command "set config DEBUG_SCHED_ALL=1." This causes a great deal of debugging information to be displayed and sent to the log file. Then, the administrator can watch while the user resubmits the lookup request. If multiple servers are involved, it's important to do this debugging at all of them in order to isolate the problem. (Note: The server must be restarted in order for this flag to take effect.)
2. If these debug messages include "not found" text, it indicates that there is no data for Peter in the BUSYTIME.NSF file -- possibly the result of the problems with his Person document discussed above.
3. If the debug information shows "no access" messages, it indicates that Peter may have set restrictions in his Calendar Profile on who can access his free time data.
4. The administrator can also enter the command "tell sched show <username>" at the server console. This will produce data that looks like the following:

03/24/98 10:39:54 AM SchedMgr: Peter Miller is busy from 04/25/98 08:45:00 AM to 04/25/98 09:30:00 AM

03/24/98 10:39:54 AM SchedMgr: Peter Miller is busy from 04/25/98 10:00:00 AM to 04/25/98 11:00:00 AM

03/24/98 10:39:54 AM SchedMgr: Peter Miller is busy from 04/25/98 01:30:00 PM to 04/25/98 02:30:00 PM

03/24/98 10:39:55 AM SchedMgr: Peter Miller is busy from 04/26/98 12:00:00 PM to 04/26/98 02:00:00 PM

03/24/98 10:39:55 AM SchedMgr: Peter Miller is busy from 04/26/98 03:30:00 PM to 04/26/98 04:30:00 PM

Again, if data for Peter Miller is found with this command, it indicates that Tim's problems with accessing the free time information are probably the result of access restrictions set by Peter. On the other hand, if no data is found, it indicates that either there are problems with Peter Miller's Person document, or that Peter has no Calendar Profile and no calendar entries in his mail file. The easiest way to correct the latter case is to have Peter create a single calendar entry and then use the server console command "tell sched validate Peter Miller."

Users in a different Notes domain
Now, let's look at another of Tim's invitees, Amy Ward. The free time lookup for Amy Ward worked, even though her free time information is on a server that's in a different Notes domain than Tim's home server, Ajax.

Why did the lookup work? When Tim initiated the lookup request, Notes first looked in his Personal Address Book for an entry for Amy Ward, and found a document that included her complete hierarchical name, "Amy Ward/Sales@SALES." ("Acme" is the name of the company all the invitees work for, and "SALES" is the name of a domain different from the one Ajax is in.) Then, Notes sent the request with Amy's name and domain to Ajax. (If no entry had been found for Amy in Tim's Personal Address Book, Ajax would have looked for a Person document in its Public Address Book. The Person document would need to include the same information.) The Calendar Connector task checked the Public Address Book for a Domain document for SALES. It found an Adjacent Domain document, and in its CalendarServer field, found the name of the server in that domain that accepted free time queries. The query was passed, and Amy's information returned.

If Peter Miller's mail file, like Amy's, were in a different Notes domain, what problems might cause his data to be missing? Any one of the following problems:

• There are connectivity problems or security restrictions that affect communications with the adjacent domain or server -- some hop along the path to finding out the user's freetime information either can't be connected to via the existing network, or that server doesn't grant privileges for the connection.
• Peter Miller's full address in Tim's Personal Address Book (or in Ajax's Public Address Book) is for an invalid domain (the result, perhaps, of changes in the Notes system, or perhaps just a misspelling in his Person document), or a domain that Ajax does not have an Adjacent Domain document for.
• The Domain document for SALES in the Ajax Public Address Book is missing or invalid in some way.
• The CalendarServer data for SALES is incorrect or missing in its Domain document on Ajax.

Troubleshooting different Notes domain problems
Crossing domain boundaries with free time lookups raises security and connectivity issues that aren't a factor when both the invitation-issuer and the invitee are in the same domain. For instance, if the SALES domain is not cross-certified with the domain that includes Ajax, then that could cause "no access" messages to be displayed on the Ajax console. Troubleshooting this case requires the intervention of a server administrator, who can then access the server console:
1. Tim should recheck his Personal Address Book entry for Peter Miller (or the Person document in the Ajax Public Address Book), and an administrator should make sure that the Public Address Book on Ajax has an Adjacent Domain document for Peter's domain.
2. An administrator should check that the Domain document for SALES in the Ajax Public Address Book is set up correctly. In particular, the CalendarServer data needs to be correct. Calendar servers can change, and the changes may not have propagated correctly.
3. If there are connectivity problems or security restrictions in reaching the adjacent domain or calendar server, an administrator should access the console of the calendar server in the other domain as well as the Ajax console to debug. (See the next section for more information on the debugging.)

A quick common-sense test is to ask a user in the SALES domain to try to schedule a meeting with Peter Miller. If the free time lookup returns results for Peter, then connectivity or security problems between Ajax and the SALES calendar server are indicated.

An administrator can also try tracing the connection from the administration client on Ajax. (The Trace Connection feature is available by choosing Files - Tools - User Preferences, selecting Ports, and clicking Trace Connection.) This should be done from the administration client, because a connectivity test from Tim's client will not work -- he would be testing connectivity between his client and the other server, not between Ajax and the other server. Even if the trace from Ajax fails, it may provide enough information for an administrator to find and fix the problem.

If the trace succeeds and the Ajax console displays "no access" messages, then Peter's Freetime Options settings for access become the likely suspect. A more remote possibility is a cross-certification problem between Ajax and Peter's server.

Logging debug information
Troubleshooting problems across domain boundaries involves using the same console commands to display debug messages, but it can be hard for one administrator to watch multiple consoles at once. The log files capture much of the information to their Miscellaneous Events view documents, based on the time that the output was generated. Some output, however, is not sent to the log file. To capture this data, set the DEBUG_OUTFILE variable in the server's NOTES.INI file. When you include the setting "DEBUG_OUTFILE=<full_pathname_plus_extension>" and the server reinitializes all console output, the messages that normally go into the log file, plus all debug messages, will go into this new file. This can be a high volume of data, so once the necessary output has been captured, you should remove the "outfile" variable from the NOTES.INI to minimize disk space consumption, and then reinitialize the server.

Users in other calendar domains
Now, let's look at why the lookup for Sarah Moskowitz worked. The Person document for Sarah Moskowitz is in the Ajax Public Address Book, but the document indicates in its CalendarDomain field that Sarah's free time information is kept in a different domain. The check of Ajax's Public Address Book yielded a Foreign Domain document. The document's CalendarSystem field identified the name of the plug-in program that does the lookups on that server (in Sarah's case, it was Organizer's Calendar Connector). The CalendarServer field in that Domain document provided the name of the server to route the request to. A query was sent, and the results were returned to Tim's client.

If Peter Miller's free time data, like Sarah Moskowitz's, were kept in Organizer, or in another of the calendar systems supported by a Calendar Connector plug-in -- OfficeVision or Time and Place -- what might cause his data to be missing? In addition to many of the problems discussed above, which revolve around errors or omissions in the Calendar Profile or Person document, it might be one of the following problems:

• A path problem -- the Organizer data may have been moved, but the Notes documents that point to it may not have been properly updated.
• A connectivity problem -- the Calendar Connector task cannot connect to the specified CalendarServer to pass along the request, or the request times out from the Calendar Connector's point of view.

Troubleshooting foreign domain problems
The architecture of the Notes calendar application makes little distinction between the native Notes calendar and calendars maintained in other applications, so troubleshooting foreign-domain problems is very much like working with a problem that crosses domain boundaries within Notes. There is a point, of course, at which the other application may become the problem, and diagnosing the effects of user settings and internal security in those applications is beyond the scope of this article. But if the OfficeVision system is returning results for its users, then common sense says it should probably work for Notes users, too. The troubleshooting process uses the same tools of console messages and logging to track a free time request from server to server, to see where the chain of connectivity breaks.

So, you may again have one of the following problems:

• A path problem, in the same way that PC users create path problems when they move data or program files from one hard drive or directory to another, is less likely with Notes, because it doesn't use paths in quite this way. If Organizer data files are moved from one disk to another, for example, it shouldn't affect free time lookups, because the Organizer Calendar Connector will still be in communication with the Organizer server, which should still be able to find its data. If an OfficeVision user's free time information that had previously been available to a Notes user is suddenly unavailable, user error (inadvertently changed settings, for example), or a temporary problem like a downed server, are more likely to be at fault.
• A connectivity problem may occur within the bounds of the Notes system, because of errors in a Domain document, for example, or as the result of temporary network difficulties.

Foreign domains are "foreign" to Notes in a couple of senses. One is that the application running in that domain is different from Notes. The other is that foreign domains are likely to be physically removed from the Notes environment -- they may run on different platforms, and/or on different networks with only limited connections to Notes. Connectivity may be concentrated at a single port of entry, and any problem becomes a 100% failure.

Conclusion
These examples show that in troubleshooting free time lookup problems, the relative positions of the inviter and invitee are important. If they are logically "close" -- if they share the same home server, for example -- and one user can't see the other's free time information, then the problem is almost certainly related to access restrictions rather than connectivity problems. But as the "distance" increases -- if the invitee is in a different Notes domain, uses a different calendar product, or even a different platform -- the possibility of connectivity being the problem rises. Diagnosing a connectivity problem usually requires administrator tools -- access to the console, debugging settings, and system logs. Diagnosing an access restrictions problem may be as simple as a phone call and the question, "What does your Calendar Profile look like?"

ABOUT JOHN
John Banks-Binici is a software architect at Iris, and worked on much of the network "plumbing" that is used to support, among other things, free time lookups. He's currently working on mail and directory issues for R5. He also plays guitar in Iris's rock band the "Iris Notes."

ABOUT BRUCE
Bruce Kahn is a senior software engineer at Iris, and has been working on the Notes calendar and scheduling (C&S) features for more than two years now. He's also spent much of that time working to help develop the new IETF C&S standards of iCalendar, iTIP and iMIP. Bruce's primary areas of responsibility are back-end C&S (the SchedMgr), evolving Internet standards for C&S and LDAP and, now, the POP3 server. He spends what free time (:^}) he has outside of Iris as the exhausted father of toddler twins, a Red Cross First Aid, CPR and Disaster Instructor and Volunteer, an amateur magician and a devoted Dilbert fan.