Agents for updating calendar entries and resource reservations for Russian repeal of daylight saving time 2011
Russia is ending their observance of daylight saving time (DST) in 2011 starting October 30th. After October 30th, seven of the eight time zones that Russia occupies will stay on Summer time, except Magadan which will move forward one hour to UTC+12. For all time zones except Magadan, any existing calendar entry that falls outside the previous DST period will appear one hour off after the operating system has been patched with the updated time zone rules. For Magadan, all calendar entries will appear one hour later than expected, since Magadan did not previously observe DST.
Impacted time zones as listed under Microsoft Windows are:
|Time Zone Name||Widows Time Zone Description|
|Russian Standard Time||(UTC+03:00) Moscow, St. Petersburg, Volgograd|
|Ekaterinburg Standard Time||(UTC+05:00) Ekaterinburg|
|N. Central Asia Standard Time||(UTC+06:00) Almaty, Novosibirsk|
|North Asia Standard Time||(UTC+07:00) Krasnoyarsk|
|North Asia East Standard Time||(UTC+08:00) Irkutsk, Ulaan Bataar|
|Yakutsk Standard Time||(UTC+09:00) Yakutsk|
|Vladivostok Standard Time||(UTC+10:00) Vladivostok|
|Central Pacific Standard Time||(UTC+11:00) Magadan, Solomon Is., New Caledonia|
The above time zones are being updated to the following on Microsoft Windows:
|Time Zone Name||Widows Time Zone Description|
|Russian Standard Time||(UTC+04:00) Moscow, St. Petersburg, Volgograd|
|Ekaterinburg Standard Time||(UTC+06:00) Ekaterinburg|
|N. Central Asia Standard Time||(UTC+07:00) Novosibirsk|
|North Asia Standard Time||(UTC+08:00) Krasnoyarsk|
|North Asia East Standard Time||(UTC+09:00) Irkutsk|
|Yakutsk Standard Time||(UTC+10:00) Yakutsk|
|Vladivostok Standard Time||(UTC+11:00) Vladivostok|
|Magadan Standard Time||(UTC+12:00) Magadan|
For all time zones except Magadan, any existing calendar entry that falls outside the previous DST period will appear one hour off after the operating system has been patched with the updated time zone rules. For Magadan, all calendar entries will appear one hour later than expected, since Magadan did not previously observe DST.
Resolving the problem
For a general overview of actions to take, refer to "Steps to prepare Notes/Domino for Russian Repeal of Daylight Saving Time 2011" (#1569946).
IBM has prepared a set of LotusScript agents that will update any existing calendar entries, calendar profiles, resource reservations, and resource documents on a mass basis that were created prior to the application of an operating system patch for these time zone changes.
Two agents have been created to update documents impacted by this DST change:
- An Administrative Calendaring Update Agent (or Admin agent) designed to update all impacted calendar entries in a user's mail file as well as time zone specific calendar profile fields.
- An RnR Update Agent designed to update all impacted reservation documents as well as time zone specific fields contained in Resource documents in a Resource Reservations database.
When a Date/Time field value is composed in Lotus Notes, its value is computed as ticks from UTC. A time zone's offset from UTC changes when it enters and leaves daylight saving time. For example, when Moscow enters DST, its UTC offset changes from UTC+3 to UTC+4, thus "springing forward". When it leaves DST it changes from UTC+4 back to UTC+3, thus "falling back". Calendaring entries falling in the old DST period between October 30th 2011 and March 25th 2012 will have been calculated assuming UTC+3. Moscow is changing its UTC offset permanently to UTC+4, and is no longer observing DST. Because of this, after the operating system's time zone rules are updated to reflect the repeal of Russian DST, calendaring entries that fall within the old DST period will appear one hour off from when they were originally scheduled. The same is true for all Russian time zones except Magadan, which did not previously observe DST, but is moving to UTC+12. Because of this all calendar entries and resource reservations created in the Magadan time zone will appear one hour off.
The agents operate by recalculating the date/time values of calendar entries and room/resource reservations in the impacted time zones to their correct UTC offset. The agents will act on entries that are scheduled in an impacted time zone regardless of whether the mail file owner is the chair or an invitee. The agents will not act on entries which have been created or are chaired in an unaffected time zone but have attendees which are located in an affected time zone. The agent does not need to process those entries for them to display correctly.
The agents will update impacted documents to show the correct time both in the Calendar view and in the open document itself. Notes Standard clients prior to version 8.5.3 must be patched with a fix for SPR# PANN8FFEFV, which includes updated Java time zone rules for Russia contained in the Notes Client. This is required for the Calendar grid to display entries correctly in the Standard client after the agents are run. This is not a requirement for the Basic client.
NOTE: A fix for SPR# PANN8FFEFV is included in Interim Fix 1 for Notes 8.5.2 Fix Pack 3. For a direct download link, see technote #1569767.
1. Assess which of the optional operating modes (described in "Agent Options") are applicable to your environment, being sure to review the advantages and disadvantages of each option.
2. Review the "Best Practices and Warnings".
3. For best performance, run the Calendaring "Admin" agent as a background agent, and run multiple instances to further shorten total runtime. See the "Best Practices and Warnings" section for details.
What does each agent update?
The primary goal of each agent is to update the following individual fields to reflect the new DST rules, within each affected document:
The StartDateTime and EndDateTime fields are rebuilt based on the new time zone rules, which are updated in the StartTimeZone and EndTimeZone fields. The Resource Reservation agent also updates the internal fields $Times1 through $Times7 for relative Resource documents.
The StartTimeZone and EndTimeZone fields are structured to contain the following attributes based upon the time zone rules stored on the operating system at the time the document was created:
|Time zone offset from GMT.|
|Daylight saving time (DST) observed flag. 1 means DST is in effect; 0 means it is not. If equal to 1, a value should be supplied for DL.|
|DST law identifying the <StartMonth> <StartWeek> <StartDayOfWeek> <EndMonth> <EndWeek> <EndDayOfWeek>.|
|Host-specific time zone index. (Optional)|
|Time zone name.|
The agents check the StartTimeZone or EndTimeZone to see if any entries match the original StartTimeZone/EndTimeZone values and update them to the Updated StartTimeZone/EndTimeZone values. As you can see, the StartTimeZone/EndTimeZone values are based off of the time zone settings of the workstation that composed the impacted calendar entry or resource reservation.
|Original Time Zone Name||Original Windows Time Zone Description||Original StartTimeZone/EndTimeZone Value|
|Russian Standard Time||(UTC+03:00) Moscow, St. Petersburg, Volgograd||"Z=-3$DO=1$DL=3 -1 1 10 -1 1$ZN=Russian"|
|Ekaterinburg Standard Time||(UTC+05:00) Ekaterinburg||"Z=-5$DO=1$DL=3 -1 1 10 -1 1$ZN=Ekaterinburg"|
|N. Central Asia Standard Time||(UTC+06:00) Almaty, Novosibirsk||"Z=-6$DO=1$DL=3 -1 1 10 -1 1$ZN=N. Central Asia"|
|North Asia Standard Time||(UTC+07:00) Krasnoyarsk||"Z=-7$DO=1$DL=3 -1 1 10 -1 1$ZN=North Asia"|
|North Asia East Standard Time||(UTC+08:00) Irkutsk, Ulaan Bataar||"Z=-8$DO=1$DL=3 -1 1 10 -1 1$ZN=North Asia East"|
|Yakutsk Standard Time||(UTC+09:00) Yakutsk||"Z=-9$DO=1$DL=3 -1 1 10 -1 1$ZN=Yakutsk"|
|Vladivostok Standard Time||(UTC+10:00) Vladivostok||"Z=-10$DO=1$DL=3 -1 1 10 -1 1$ZN=Vladivostok"|
|Central Pacific Standard Time||(UTC+11:00) Magadan, Solomon Is., New Caledonia||"Z=-11$DO=0$ZN=Central Pacific"|
|Updated Time Zone Name||Updated Windows Time Zone Description||Updated StartTimeZone/EndTimeZone Value|
|Russian Standard Time||(UTC+04:00) Moscow, St. Petersburg, Volgograd||"Z=-4$DO=0$ZN=Russian"|
|Ekaterinburg Standard Time||(UTC+06:00) Ekaterinburg||"Z=-6$DO=0$ZN=Ekaterinburg"|
|N. Central Asia Standard Time||(UTC+07:00) Novosibirsk||"Z=-7$DO=0$ZN=N. Central Asia"|
|North Asia Standard Time||(UTC+08:00) Krasnoyarsk||"Z=-8$DO=0$ZN=North Asia"|
|North Asia East Standard Time||(UTC+09:00) Irkutsk||"Z=-9$DO=0$ZN=North Asia East"|
|Yakutsk Standard Time||(UTC+10:00) Yakutsk||"Z=-10$DO=0$ZN=Yakutsk"|
|Vladivostok Standard Time||(UTC+11:00) Vladivostok||"Z=-11$DO=0$ZN=Vladivostok"|
|Magadan Standard Time||(UTC+12:00) Magadan||"Z=-12$DO=0$ZN=Magadan"|
(The terms UTC and GMT are interchangeable in the above tables)
It is important to note that Microsoft has done the following when updating the Russian time zone rules for the repeal of DST:
- Removed Ulaan Bataar from the North Asia East time zone and placed it in its own time zone
When the agents are run they will not be able to differentiate between calendar data that needs to be changed to the new Magadan time zone and those that need to stay in Central Pacific. Any calendar entry that is encountered which is scheduled in the Central Pacific time zone will be moved to the Magadan time zone. Ulaan Bataar was also split out into a new time zone from the North Asia East time zone. Any calendar entry created in the North Asia East time zone will stay in that time zone when being processed by the agent. Calendar entries that need to be scheduled in the Central Pacific or Ulaan Bataar time zones must be rescheduled manually.
Administrative Calendaring Update Agent
This agent will update all documents that meet the following conditions:
Additional agent behavior of note:
RnR Update Agent
This agent will update all documents that meet the following conditions:
Additional agent details:
- If a repeat entry has a missing or corrupt parent document the agent will add the field $TimeZoneAgent with a value of 0 to the repeat document. In such cases the issue will be noted in the report, noting the repeat document's Universal ID (UNID) with the text "Unable to process document: <UNID> Its parent document was not found." Such entries must be manually recreated.
The configuration of important options is discussed further below. Both agents have the ability to operate in a report mode. This mode will count the number of documents that need to be acted on by the agent. By default agents act only on entries within 2011 and 2012.
Both agents are written in LotusScript. There are options within the agent's Initialize event in the area labeled "USER DEFINABLE VARIABLES". The information below details the options, including which version they are available in, their default behavior, as well as any Pros and Cons related to their usage:
Set the "ReportMode" variable to "True" to run a report which does not update documents, or "False" to update documents. Default is False.
- The agents tally and report the total documents for all databases that would be processed by the agents.
- When run in report mode, the agent will still flag orphan repeat entries by creating the field $TIMEZONEAgent with a value of 0. This ensures better performance and additionally guards against problematic calendar data.
Years of Data to Act on
Agents that do not act on selected documents use a FOR loop to determine the limits for the year(s) of the data acted on. The default for the loop is 2011 to 2012, and will act on documents falling outside of Russia's DST period for all zones except Magadan, in which case all calendar entries will be processed from today forward.
Note: The FOR loop can be manipulated by directly editing the code line "For yr=2011 To 2012", which is present in the core section of the Initialize event rather than the section titled "USER DEFINED VARIABLES".
Running Mail File "Admin" Agent as on a Server (Recommended)
Set the "isRunningOnServer" variable to "True". Default is True. You must additionally set the "fileName" variable to the input text file located on the server. The details for this file are discussed further below.
Mail Rescheduling Notices. Set the "CanNotify" variable to "True" to send rescheduling notices for entries being processed by the agents. Default and recommended setting is False.
- Not sending reschedule notices minimizes user confusion by suppressing reschedule notices.
- Not sending reschedule notices causes Notes users in a different geographic region to not be aware of time changes for meetings rescheduled by the agent, unless they also have the Admin agent run against their mail file.
- It is possible for a conflict to occur as the agent is processing C&S entries. For example, User A reserves a room at 1:00 PM and 3:00 PM for separate meetings. User B reserves a room at 2:00 PM. After the operating system patch is applied say User A's meetings will appear at 2:00 PM and 4:00 PM, and User B's meeting will appear at 3:00 PM. If User B's meeting is processed first by the agent it will reschedule the room reservation back to the correct time of 2:00 PM. However, since this slot is already occupied by User A's meeting, it will be rejected by R&R autoprocessing.
Processing Magadan calendar entries. Because all calendar entries from until the end of 2012 need to be updated by the agent, processing entries scheduled in Magadan comes with a significant amount of overhead. An administrator may optionally turn off the processing of Magadan calendar entries by setting processMagadan=False. Default is true. You may also set the variable processMagadanOnly=true at a later time when you want to renable the processing of Magadan entries. The default is for processMagadanOnly is false.
Best Practices & Warnings
- RNRMgr (while running the "RnR" agent)
The agents are provided with the library references as noted:
The Calendaring and Scheduling agents use:
The Resource Reservation agents uses:
2) Running multiple background agents to get concurrent processing power.
3) Running agent on a powerful server machine (in our tests, this cut the runtime almost in half).
Steps for Running the Administrative Calendaring Update Agent
The "Admin" agent should be created in a database based on the standard mail template on a Domino server where the mail files to be processed also reside. The agent is designed to be run by an administrator who has at least Editor access to the mail files to be acted on. Although the agent can be run from the actions menu in a Notes Client, it is recommended to be run in the background on a Domino server. It is suggested that this agent be run during off-peak hours so as not to disturb usual mail routing performance. The agents create two report documents per execution, one for the Russian time zones repealing DST and one for Magadan. The agent requires that the location of a text file (e.g., c:\mailfiles.txt) be entered when prompted. The data in the text file should be formatted like this:
NOTE: Wildcards cannot be used within the input file. If the extension is not specified, then .NSF will be assumed. If you have mail files with another extension, for example ND5 or ND6, then the extension must be specified.
Running the Agents in the Background on a Domino Server
1. On the server where the mail files to be processed reside, create a new database based off of the standard mail template and open it in Designer.
2. Select Create->Design->Agent from the Designer menu.
3. Make sure agent type is set to LotusScript and give the agent a name, like AdminAgent.
4. Under the objects tab the name of the agent will be selected. Select all of the text in the programmer's pane and delete it.
5. Open the lss file attached here, select all, and copy and paste the code into the programmer's pane.
Update_Timezone (admin) - Russia 2011.lss
6. Create an input .txt list file for the agent. The Admin agent requires a list of mail files to run against. This can be either done manually using a text editor (such as Notepad), or you can generate a list of mail files on a server by issuing the following command on your Domino server console:
load convert -l c:\mailfiles.txt
The command will create a file named “mailfiles.txt” in the c:\directory on the Domino server.
Note: The command parameter “-l” is a dash followed by a lowercase "L". If you use this command to create the input list text file and you plan to run the Admin agent manually from a Notes client, then the text file must be moved from the server system to the client system.
Note: Wildcards are not permitted in the input file.
For a clustered server the command "load convert -l..." will produce a list of those mail files belonging to only those users who have the cluster as their primary mail server. This means the list will not contain an entry for each and every mail file on a clustered server. This behavior can actually be beneficial if you are running multiple versions of the agent. One agent could use the list from one cluster, and a second agent could use the list from a second cluster.
Warning: It is important that you do not apply the agent to the same mail files on more than one cluster, as doing so will result in undesired behavior such as replication conflicts and duplicate entries.
7. Set the Agent Options fileName and isRunningOnServer variables (Note: These are set in the User Defined Variables section of the code). For example:
8. Per the "Agent Options" section configure ReportMode=True to create a report in the Drafts view of the database showing the number of documents that would have been updated by the agent, or set ReportMode=False to update calendar entries and profile documents.
9. In the Basics section, under the properties tab:
- Set the Trigger to Scheduled.
- Set the Schedule to never.
- Set the target to "All documents in database".
10. In the security section, under the properties tab, change agent properties to run with full administration rights:
11. Ensure that the agent signer (last person to save or enable it) is listed in the Full Access Administrators entry in the Server document within the Domino Directory. The entry is found on the Security tab. If the signer is not listed, then they must be added.
12. Manually trigger the agent on the server by issuing the following command on the server console (Note the double quotation marks around the database name and single quotation marks around the agent name):
tell AMGR Run "DST.nsf" 'AdminAgent'
Note: You can configure the agent to run on a specific schedule, but ensure the "Max LotusScript/Java execution time:" in the Agent Manager section of the Server document is set to a high value, so that agent execution to complete.
13. Two log documents will be created in the Drafts view of the database. One for the Russian time zones repealing DST, and one for Magadan. View the contents of these document for any errors and for a report of how many documents were processed.
1. To run as multiple instances (i.e., four instances), copy/paste the agent that you created using the above steps multiple times in the same database, and change the name to "AdminAgent1", "AdminAgent2", and so on.
2. Ensure you have the server setup to run the desired number of concurrent agents in the Server document in the Domino Directory. The "Max concurrent agents" setting is found on the Server Tasks -> Agent Manager tab. Note: There are separate settings for "Daytime Parameters" and "Nighttime Parameters," make sure that you set each as desired.
3. Split the input text file evenly into separate files for each instance of the agent. For example, mailfiles1.txt, mailfiles2.txt, and so on. Each text file should contain its own unique content.
4. Edit each agent, so that the fileName points to a different text file for each agent. For example, in AdminAgent1, fileName should be fileName=c:\mailfiles1.txt, in AdminAgent2, fileName should be fileName=c:\mailfiles2.txt, etc...
5. Simply issue "Tell AMGR Run" for each of the individual copies of the agent:
i.e. for 4 agents it would be the following
Tell AMGR Run "DST.nsf" 'AdminAgent1'
Tell AMGR Run "DST.nsf" 'AdminAgent2'
Tell AMGR Run "DST.nsf" 'AdminAgent3'
Tell AMGR Run "DST.nsf" 'AdminAgent4'
Steps for Running the RnR Update Agent
The RnR Update Agent agent should be placed in the Resource Reservations database (or template, if desired) and run from the Resource Reservations (R&R) databases. The agent should be run by an administrator who has at least Editor access to the database. The agent is executed via the Actions menu and it creates a report document per execution.
Note: These agents require the coding of a variable within the Initialize event of the agents. The string variable strRnRType must be set as described below:
- "R7" if server is running RnRMgr server task on R&R database (Default)
- "R6" if server is NOT running RnRMgr and the R&R database is using a pre-R7 template (Legacy, and should no longer be needed)
1. Shut down the RnRMgr task on the Domino server. This can be done by issuing a 'tell RnRmgr q' command on the Domino server console.
2. Open the RnR database you'd like to process in Designer. These changes can also be made to the resource reservations template, so that they are propagated out to all RnR databases by the design task.
3. Create a form to view the log output from the agent by selecting Create->Design->Form. Name the form DSTAgentErrorLog.
4. Right Cick on the blank form and select Create Field. Name the field Subject.
5. Right click on the form and select Create Field. Set the field type to Rich Text. Name the field Body.
6. Save and close the form.
7. Create a view to display the agent log output by selecting Design->Create->View in Designer.
8. Name the view DST Report.
9. In the By formula field, delete the existing formula and replace it with:
10. Save and close the view.
11. Create the DST agent by selecting Create->Design->Agent from the menu. Name the agent RnRAgent and make sure the type of the agent is set to LotusScript.
12. Under the objects tab the name of the agent will be selected. Select all of the text in the programmer's pane and delete it.
13. Open the lss file attached below, select all, and copy and paste the code into the programmer's pane.
Update_Timezone (RnR) - Russia 2011.lss
14. Under the Properties tab, in the basics section, set the Target to None.
15. Per the "Agent Options" section configure ReportMode=True to create a report in the Drafts view of the database showing the number of documents that would have been updated by the agent, or set ReportMode=False to update calendar entries and profile documents.
16. Save and close the document.
17. Run the agent by navigating to the Reservations by Date view and selecting Actions->RnRAgent.
18. You will be asked if you have quit the RnRMgr task.
If you have quit the task per Step 1, then select OK, then No in the following dialog.
If you have not quit the RnRMgr task select Yes, and quit the task. If not this could load to agent failure and possible damage to reservations.
13. A log document will be created in the DST Report view of the database. View the contents of this document for any errors and for a report of how many documents were processed.
14. When you are finished start the RnRMgr task again by issuing a load RnRMgr.
Post Agent Execution Requirements
Users need to:
- See whether they have received any emails noting a "Decline" notification.
- Review their Calendar to see whether the shifting of any entries resulted in a timeslot being unexpectedly double booked. Note: Some users may have already had a timeslot double booked and in those cases it would be expected that the adjusted entries resulted in an expected double-booking.
Administrators need to:
- Review the output log from the agent. If the agent noted it could not process a mail file due to an ACL rights issue, then take steps to adjust the ACL of the mail files so that the proper access is provided. You may also want to notify users if there are cases where an entry's parent is missing, as the chair may need to re-invite a user and/or recreate the meeting. If any errors are reported, see the "Details on Possible Error Conditions" section below.
- Review the Resource Reservation database for double bookings. Notify the chairs of the double booked resource or room so they can take action to determine who will retain the resource/room, and who will need to reschedule the resource/book a new room.
The tables below document the behavior and actions that will occur if an entry is rescheduled without issue (non-conflict), or if there is a conflict.
Reschedule Notifications Enabled
Reschedule Notifications Disabled
|C&S||Entry is rescheduled.||Entry is rescheduled.|
|C&S RR workflow||An acceptance email will be sent to the chair.||The meeting will we reflected at the correct time. No acceptance email will be sent.|
|RR direct||Entry is rescheduled.||Entry is rescheduled.|
Reschedule Notifications Enabled
Reschedule Notifications Disabled
|C&S||The time slot will be double booked.||The time slot will be double booked.|
|C&S RR workflow||A decline email will be sent to user who does not obtain the reservation. Which ever notice is in the slot with the new time zone rules first, will win.||The entry will be double booked.|
|RR direct||The room/resource will be double booked for that time slot.||The room/resource will be double booked for that time slot.|
Details on Possible Error Conditions
The following details common errors which may be observed in the log documents
"Unable to process document: <UNID> Its parent document was not found."
An agent will report this entry if a repeat meeting entry has a missing or corrupt parent document. Note: If the code did not check for a invalid parent then this condition would report a 4670 error. Notes cannot process orphaned calendar entries. If you are an invitee, the chair must remove and then re-add you to the invitation so you have a new meeting entry to act on. If you are the chair, you must delete the existing meeting and recreate it. Note: Such "orphan" entries are identified by the presence of the field $TIMEZONEAgent, with a value of 0 (zero).
"Error number 4670 (User-defined error) occurred at line <#> while processing UNID <UNID>"
There are different cases that cause this error and different solutions, as follows:
- A reschedule notice cannot find a person in the Domino Directory.
The chair must edit the entry and remove the invitee, save the entry, and then reschedule it.
- The document or its parent (if it is a Repeat) is a Replication/Save conflict.
A common case is if a user accepted and/or declines an invite from a server, a local replica, or mobile device. This will cause a replication conflict at the parent level and usually causes at least one "twin" (the meeting shows up twice in your calendar at a given time before agent processing). The agent will process all "twins" that it can. If one or both of the twins' parent points to a replication conflict, the agent will not process that entry. Users should be aware of this and either attend the meeting at the normal time, or confirm with the chair when the meeting occurs. The twin/duplicate entry should not be deleted as this will generate a Decline. The entry will need to be ignored.
|Messaging Applications||IBM Domino|
More support for:
Calendaring and Scheduling
Software version: 8.0, 8.0.1, 8.0.2, 8.5, 8.5.1, 8.5.2, 8.5.3
Operating system(s): Linux, OS X, Windows, iOS
Software edition: All Editions
Reference #: 1569776
Modified date: 28 October 2011