Notes/Domino Fix List
SPR # MGAN5EDTNNFixed in 5.0.12 releaseTemplate fix: mail50.ntf, mail50ex.ntf



Product Area: Client; Template Technical Area: Mail Client - Rules Platform: Cross Platform

SPR# MGAN5EDTNN - Users can now create a disable Rule and enabled it later.

Technote Number: 1088058

Problem:
This technote applies to mail templates in Notes 6.0/5.0 releases, prior to the
mail templates which shipped with Notes 6.5.4/6.0.5. Integral parts of the
logic were changed in the 6.5.4/6.0.5 mail templates, thereby resolving the
majority of issues.

-- For details on a minor numbering flaw occurring in the 6.5.4/6.0.5 mail
templates that can cause an enabled rule to not run, refer to Document
#1216891, "Mail rules not executing as expected in Notes 6.5.4/6.0.5."

-- For details on minor mail rule issues relative to the Notes 7.0 mail
template, refer to Document 1217940, "Mail rule issues with the Notes Domino
7.0 mail template."

If you cannot upgrade to Notes 6.5.4 or 6.0.5, refer to section II. Suggested
code updates for templates prior to 6.5.4/6.0.5 for updates to the mail
templates that will avoid a number of issues.

In order to repair rules that are not behaving as expected, refer to section I.
Agent for reordering rules and clearing the Calendar Profile of rules that run
unexpectedly.

Sections III-VI provide more specific information on various issues and their
related software problem reports (SPRs).

Table of Contents

I.
Agent for reordering rules and clearing the Calendar Profile of rules that run
unexpectedly
II.
Suggested code updates for templates prior to 6.5.4/6.0.5
III.
Disabled rules that still trigger
IV.
Deleted rules that still trigger
V.
Rules that are enabled but do not run
VI.
New mail rules run but do not appear in Rules folder
VII.
Background information on mail rule functionality
*********************************************************************
I. Agent for reordering rules and clearing the Calendar Profile of rules that
run unexpectedly
With all of the rules enabled and then disabled, the following agent can be run
to reorder the OrderNum field of the rules. To additionally clear the Calendar
Profile of rule entries for rules running unexpectedly, additional code is
provided which can be uncommented. The agent should be created in the problem
mail file as a "Run Once" agent in Notes 5.0 releases and with a target of
"None" in Notes 6.0 releases.

An enhancement request was submitted to Quality Engineering as SPR# RWAS547K42
that requests additional functionality be added to reorder the internal
numbering used for rules. There are currently no plans to address this issue.

NOTE: Notes Support is not available to make further modifications or
enhancements to the following code.

Dim s As New notessession
Dim db As notesdatabase
Dim rulesfolder As notesview
Dim rules As notesviewentrycollection
Dim rule As notesviewentry
Dim ruledoc As notesdocument
Set db=s.currentdatabase
Set rulesfolder=db.getview("Rules")
Set rules=rulesfolder.allentries
Set profile=db.GetProfileDocument("CalendarProfile")
'Optional code to remove rule entries from the Calendar Profile which did not
disable as expected.
'The code can be used if you want to "clean out" the rule entirely in the
profile.
'NOTE: The code below will disable the C&S Miniview rule so it must be manually
re-enabled.

'If profile.getitemvalue("Use_CalendarRule")(0) = "1" Then
' profile.Use_CalendarRule = "0"
'End If
'Set Count=profile.getfirstitem("$FilterFormulaCount")
'Call count.remove
'Forall ff In profile.Items
' If ff.type = 1536 And Lcase(Left(ff.name,15)) = "$filterformula_" Then
' Call ff.remove
' End If
'End Forall
'Call profile.Save(True, True)
If profile.getitemvalue("Use_CalendarRule")(0) = "1" Then
number=1
Else
number=0
End If
Set rule=rules.getfirstentry
While Not rule Is Nothing
Set ruledoc=rule.document
ruledoc.ordernum=Cstr(number)
Call ruledoc.save(True, True)
Set rule=rules.getnextentry(rule)
number=number+1
Wend

NOTE: Using the agent above is recommended by Notes Support for handling these
issues. Deleting the calendar profile is not optimal since it results in the
loss of all user settings found in Tools --> Preferences, such as calendar free
time, alarms, mail delegation, calendar delegation, and so on. If the profile
is deleted, then all the settings must be manually reset by the user through
the user interface. If you do decide to delete the calendar profile, users
should review their current settings under Tools --> Preferences and note the
settings before doing anything. For details on deleting profile documents,
refer to Document #1088892, "How to delete Profile documents manually or using
LotusScript."

IMPORTANT: Restart the router after clearing the Calendar Profile for mail
rules that are deleted but still running since the router can cache rules and
continue to run them even after this measure is taken.

II. Suggested code updates for templates prior to 6.5.4/6.0.5
This section details template updates which are suggested to avoid issues noted.

Rules that are enabled but do not run:
In the mail templates that ship with Notes 6.5.4/6.0.5, the following fixes are
resolved by a more extensive modification to the relative sections of code.
This issue was reported in various SPRs.

For Notes 6.0-6.0.4 and 6.5-6.5.3:
In the Rules script library, the following update should be made in the
subroutines of ButtonOKClient, ButtonOKWeb and ButtonOKQuick.

Locate the following section of code and add the lines noted:

If note.isnewnote Then ' this is a new rule
' we need a new sequence number
Set viewcollection = view.allentries
If viewcollection.count = 0 Then
If profile.getitemvalue("Use_CalendarRule")(0) = "1" Then
nrulenum=1
Else
nrulenum=0
End If
Else

For Notes 6.0.3, 6.0.4, and 6.5-6.5.3:
In the BlockUserRule script library, Declarations section, update the
FindHighestRule function as follows:

If Highest=0 Then 'Remove this line and replace with below:
If Me.m_CalProfile.Use_CalendarRule(0)="1" Then
Highest = Highest + 1
End If
FindHighestRule = Highest
End Function

For Notes 6.0-6.0.2:
In the Enable action in the (Rules) folder design, modify the line below,
adding +1:

Call profile.replaceitemvalue("$FilterFormulaCount", Cstr(FindHighestRule()+1))

Modify the Rules library's ButtonOKClient and ButtonOKWeb so that the
$FilterFormulaCount is set/incremented for new documents, regardless if they're
enabled or disabled:

' $FilterFormulaCount is the total number of rules in the rules folder
If nstate = 1 Or nstate= 2 Then ' special cases where we must increment the
$FilterFormulaCount by 1
'$FilterFormulaCount is the total number of rules in the db

Disabled rules that still trigger:
This specific issue occurs when the Calendar MiniView rule is not configured
and either a single mail rule exists and it is disabled, or multiple mail rules
exist and they are all selected to be disabled.

NOTE: This issue is fixed in the mail templates that ship with Notes
6.5.4/6.0.5.

Modify the LotusScript code within the Disable action in the Rules folder, as
follows:

For Notes 6.0.2-6.0.4, and 6.5-6.5.3:
Original code (line 23):
If Not ( Lcase( Left( items.name,16 ) ) = "$filterformula_0" ) Then '//Resave
for MiniView

Modified line:
If Not (Lcase(Left(items.name,16))="$filterformula_0" And
profile.getitemvalue("Use_CalendarRule")(0)="1") Then

For Notes 6.0 and 6.0.1:
For releases prior to 6.0.2, either update to the 6.0.2 (or later) template and
make the above correction, or replace the following area of the code as noted:

Original code (starting on line 22):
If Lcase(Left(items.name,7)) = "$filter" Then
Call items.remove()
End If

Replacement code:
If Lcase(Left(items.name,14)) = "$filterformula" Then
If Not ( Lcase( Left( items.name,16 ) ) = "$filterformula_0" And
profile.getitemvalue("Use_CalendarRule")(0) = "1") Then
Call items.remove()
End If
End If

NOTE: To repair this specific issue, there is an agent that can be used. If you
are unsure if the issue is caused by this specific scenario, it is suggested
that you use the agent supplied in section I. Agent for reordering rules and
clearing the Calendar Profile of rules that run unexpectedly to repair the
current condition.

1. Examine the document properties of the existing rules and be sure that the
one with a field value of 0 (zero) in the OrderNum field is disabled.

2. Create and execute the following LotusScript agent:

Dim session As New NotesSession
Dim db As NotesDatabase
Dim doc As NotesDocument
Dim ff As NotesItem
Set db=session.currentdatabase
Set doc=db.getprofiledocument("CalendarProfile")
Set ff = doc.GetFirstItem("$FilterFormula_0")
Call ff.Remove
If doc.getitemvalue("Use_CalendarRule")(0) = "1" Then
doc.Use_CalendarRule = "0"
End If
Call doc.Save(True, True)

3. Re-enable the Calendar "MiniView" rule if so desired.

NOTE: The issues described in the next two sections (III: Disabled rules that
still trigger and IV: Deleted rules that still trigger) were reported to
Quality Engineering as SPR# FBAY5UCKZR and were fixed in the Lotus Domino 6.5.5
MR release.

Excerpt from the Lotus Notes and Domino Release 6.5.5 MR fix list (available at
http://www.ibm.com/developerworks/lotus):

Rules
SPR# FBAY5UCKZR - After creating a rule and then disabling/deleting the rule,
the rule is not disabled. This problem has been fixed in 6.5.5.

Refer to the Upgrade Central site for details on upgrading Notes/Domino.

III. Disabled rules that still trigger
This issue occurs when the Calendar MiniView rule is not configured and either
a single mail rule exists and is disabled, or multiple mail rules exist and
they are all selected to be disabled. The result is that the first mail rule
(with an OrderNum field value of 0) is not properly disabled and it will
continue to execute.

This issue was reported to Quality Engineering as SPR# KMUR5UZN25 and was fixed
in the mail templates that ship with Notes 6.5.3/6.0.5.

Excerpt from the Lotus Notes and Domino Release 6.5.3 MR fix list (available at
http://www.ibm.com/developerworks/lotus):

Mail Client
SPR# KMUR5UZN25 - Fixed a problem where Rules remained active after being
deleted. The Disable button in the Rules folder was not taking into
consideration the exclusive MiniView Rule, resulting in the rule displaying as
"disabled" when in reality it was active.

Refer to the Upgrade Central site for details on upgrading Notes/Domino.

Workaround:
See section II. Suggested code updates for templates prior to 6.5.4/6.0.5 for
details on code revisions for earlier releases that will avoid this issue, as
well as for an agent workaround you can use to repair the present condition.

IV. Deleted rules that still trigger
If an enabled rule is deleted while open to a folder other than the Rules
folder, then the rule is not properly disabled (removed from the Calendar
Profile) before being deleted. For example, if you selected a rule and changed
views while pressing CTRL and then pressed DEL, the rule is not properly
disabled. This issue was reported to Quality Engineering as SPR# MGAN5EDSB2.

Workaround:
Refer to section I. Agent for reordering rules and clearing the Calendar
Profile of rules that run unexpectedly for an agent to repair the current
condition.

Refer to section II. Suggested code updates for templates prior to 6.5.4/6.0.5
for details on code revisions for earlier releases that will avoid this issue.

For server-based mail rules tested in 6.5.2 and 6.5.3, it was found that mail
rules that were deleted while still enabled were in force until either SET
RULES was issued from the Domino console (which showed the remaining rules as
registered), or the Domino server was restarted.

NOTE: In some cases, a rule may not be deleted but still runs and does not
display in the Rules folder. The cause may be a duplicate Rules folder, visible
only in the Designer client. It is unknown why this would occur but it may be
related to unexpected behavior during the upgrade of the mail file design. For
details on checking for a duplicate folder and recreating a Rules folder, refer
to section VI. New mail rules run but do not appear in Rules folder.

Additional Information:
There is a related issue where deleting a mail rule while the Preview Pane is
open can cause an error (in Notes/Domino releases prior to 5.0.9). For more
information on this issue, refer to Document #1084301, "Error: 'Cannot remove
NotesDocument...' when deleting mail rule if Preview pane is open."

V. Rules that are enabled but do not run:
This issue can occur due to different logic issues in the rule enablement
functionality. The numbering logic was reworked in Notes 6.5.4/6.0.5 as
reported in SPR# AANA658EUT and this may result in avoiding rule failure
scenarios which are not specifically discussed in this section.

Excerpt from the Lotus Notes and Domino Release 6.0.5 / 6.5.4 MR fix list
(available at http://www.ibm.com/developerworks/lotus):

Mail Client
SPR# AANA658EUT - Changed the code to prevent the BlockUser rule from
overriding the last existing Rule in the mail file.

Refer to the Upgrade Central site for details on upgrading Notes/Domino.

-- One issue is that newly created mail rules that are initially disabled do
not increment a necessary rule counter field. This issue is true in mail
templates in both Notes 5.0 and 6.0. Also, in Notes 6.0 templates, there is an
issue where the Enable Rule(s) action sets the rule counter to a value 1 less
than appropriate.

These issues are fixed in the mail templates that ship with Notes 5.0.12 and
6.5/6.0.3 as reported in SPR# MGAN5EDTNN.

Excerpt from the Lotus Notes and Domino Release 5.0.12 MR fix list (available
at http://www.ibm.com/developerworks/lotus):

Mail Client - Rules
SPR# MGAN5EDTNN - Users can now create a disable Rule and enabled it later.

Refer to the Upgrade Central site for details on upgrading Notes/Domino.

Workaround:
Refer to section II. Suggested code updates for templates prior to 6.5.4/6.0.5
for details on code revisions for earlier releases which will avoid this issue.

The first mail rule (with OrderNum field of 0) does not run although it's
enabled. Examination of the Calendar Profile reveals that the relative rule
entry has been overwritten by the C&S Miniview rule or a block mail sender
rule.

This issue, reported to Quality Engineering in SPR# MGAN5W4VQN, is fixed in the
mail templates that ship in Notes 6.5.4/6.0.5 by the fix made to SPR#
AANA658EUT (discussed in this section). For more details on this topic, refer
to Document #1160706, "Using the Block Sender functionality can internally
overwrite previously created rules."

Workaround:
Refer to section II. Suggested code updates for templates prior to 6.5.4/6.0.5
for details on code revisions for earlier releases that will avoid this issue.

In the mail templates in Notes 5.0 releases, there is an issue in which the
Disable Rule(s) action incorrectly sets the rules counter to a numerical value,
rather than the expected text value. This issue was reported to Quality
Engineering in SPR# JCHN52B5GF.

Additionally, given the numbering process used, enabled rules may not be
numbered contiguously. Given that release 5 will run a maximum of 50 rules per
user, it is possible that a rule may not trigger if its internal number is
greater than 49 (numbering starts at 0).

In cases where the suggested template updates or upgrades haven't been made,
some of these issues may be avoided by:

-- Prior to deleting a rule, always disable it first.

-- When creating a rule, always have it enabled/on. If you do not want the rule
enabled, highlight it in the folder and click Disable Rule(s).

Related topic SPRs:
SPR# DCOY4TX7JE: Server rules that are out of sequence will not execute. It was
assumed that the issue occurred because the rules were set up on different
replicas.

SPR# SBUR59GPW8: This requested that the maximum number of rules be increased.
In Notes 6.0 releases, the maximum is now 100. For more information on this
issue, refer to Document #1091326, "Is There a Limit to the Number of Mail
Rules Each User Can Create?"

If users are running release 6.5.3 or previous releases to 6.5.3 and report
that no mail rules are running at all, new or old, check to see if the Server
log, Console log, or Server console have the following error:

"Router: Failed to register mail rule filter 1: Insufficient memory - NSF
monitor pool is full."

Refer to Document #1156542, "Mail rules are not executing -
NSF_MONITOR_POOL_SIZE_MB to control the size of monitor buffer," for
information about how to handle this issue.

VI. New mail rules run but do not appear in Rules folder
The cause may be duplicate (Rules) folders, visible only in the Designer
client. To check if this is the case, open the mail database in Designer and
select Folders to see if there are duplicate Rules folders.

There may be several reasons why there are duplicates, the most common being
that a previous version of the folder was not removed if the mail template was
upgraded. The outdated folder should be deleted.

Sometimes, "missing" rules will appear in the remaining Rules folder and
sometimes they won't. If they still do not appear, you must create a view that
displays all documents with the form, Mailrule, and either drag them into the
Rules folder or delete them. If the rules are deleted, you may have to delete
the user's Calendar Profile as well.

To remove a duplicate Rules folder:
1. Open the mail file in the Designer client.

2. Open the Folders design list.

3. The "(Rules)" folder with the older date should typically be the one to
delete. If deleting the older folder causes issues, then repopulate the folder
using the instructions below.

To populate a Rules folder:
1. Create a view with the selection formula, Select Form="Mailrule".

2. Open the documents that appear in the view to determine which correspond to
rules missing from the Rules folder. If the rule is not within the view, do not
continue with these instructions. Instead, follow the instructions in the
Workaround section below.

3. *Drag the document into the Rules folder.

* The mail templates for Notes releases 6 and 7 intentionally prevent you from
dragging and dropping documents to and from the Rules folder. This
functionality is designed into the QueryDragDrop event. The event must be
temporarily modified to allow you to drag the rules documents back into the
recreated folder.

1. Open the mail file using the Designer client.
2. In the left pane, choose Other --> Database Resources.
3. In the right pane, choose Database Script --> QueryDragDrop.
4. Using an apostrophe, remark out the line: Continue=False.

'//Preventing drag & drop to (and from) Rules folder
If EntryName = "Rules" Or ViewName = "(Rules)" Then
' continue = False
End If

5. Save and close the Database Script design element.
6. In the Notes client, close and reopen the database if it was open during the
modifications.
7. After the rules documents are dragged into the Rules folder, repeat Steps
1-6 above, but, for Step 4, remove the comment.

VII. Background information on mail rule functionality
In many cases the number or order number contained in a rules OrderNum field
can play a role in rules running or not running unexpectedly. In order to
determine a field's OrderNum value, right-click the document, choose the second
tab, and find the OrderNum field in the list. The value will be in the right
pane.

In 5.0 releases, the first rule should be 0, the second 1, and so on. If there
are any gaps, they must be programmatically renumbered.

In Notes 6.0-6.0.4 and 6.5-6.5.3, the first rule sometimes starts with 0 and
sometimes starts with 1. All the following rules should follow in sequence and
must be programmatically renumbered if they do not.

Notes 6.0.5/6.5.4 (and later 6.0 releases), the first rule starts with 1.

In Notes 6.0 server rules, the first rule starts with 0.

When a mail rule is enabled, a $FilterFormula_# field is added to the Calendar
Profile, where x equals the number of the rule in the list, starting at 0
(except as noted above).

For example, if you have three rules in your Rules folder, and the 1st and 3rd
rules in the list are enabled, the Calendar Profile will have $FilterFormula_0
and $FilterFormula_2. This field has a formula that matches the condition of
your rule which is used to perform the rule action when mail is deposited.

When a rule is disabled, the corresponding $FilterFormula_# field is removed
from the Calendar Profile.

NOTE: In specific cases, the fact that the $FilterFormula_# field is not
deleted when a mail rule is deleted prior to being disabled is discussed in
section III. Deleted rules that still trigger (SPR# MGAN5EDSB2). By design, the
$FilterFormula_# entries are not renumbered when a rule is disabled or deleted.

The Calendar Profile also contains a field, $FilterFormulaCount, that should
coincide with the total number of rules within the mail file. The
$FilterFormulaCount should always be at least one value higher than the highest
$FilterFormula_# entry. Otherwise, the rules that fall numerically above
$FilterFormulaCount-1 will not run.

For example, if $FilterFormulaCount is 4, no $FilterFormula entries above
$FilterFormula_3 will be executed. The reason for the offset by 1 is because
the $FilterFormulaCount has a starting value of 1 and the $FilterFormula_#
entries have a starting value of 0.

NOTE: In Notes 6.0-6.0.5 and 6.5-6.5.3, by design, the numbering can be
slightly different, depending on whether the Calendar & Scheduling Configure
button has been executed. When you click the C&S Configure button, an
additional rule is created and is written to $FilterFormula_0. Any previously
existing rules are rewritten to a $FilterFormula_# entry one value higher.

For example, $FilterFormula_0 is shifted to $FilterFormula_1, and
$FilterFormula_1 is shifted to $FilterFormula_2, and so on. The
$FilterFormulaCount value is also incremented by 1. So in the case where a user
clicks the C&S Configure button, the $FilterFormulaCount value is equal to the
number of user rules. plus 1. In Notes 6.0.5/6.5.4, by design, the numbering is
designed to always start with the $FilterFormula_1.

Sample LotusScript to get a handle to the Calendar Profile document:
You can create a LotusScript agent or button with the following code in order
to get a handle to the Calendar Profile. If you enable the LotusScript Debugger
(Files --> Tools --> Debug LotusScript), you can step through the code and
expand the DOC object, and then the ITEMS array, in order to view the
$FilterFormula_# fields and the #FilterFormulaCount field. The example below
gets a handle to the Calendar Profile in the mail file specified in the current
Location Document.

Dim session As New NotesSession
Dim db as NotesDatabase
Dim doc As NotesDocument
maildbinfo = Evaluate(|@MailDbName|)
Set db = session.getdatabase(maildbinfo(0), maildbinfo(1))
Set doc = db.getprofiledocument("CalendarProfile") More >



Last Modified on 09/28/2007

Go back