When a new mail document arrives in your Inbox, typically, the sender's name, the date, and the email subject are displayed in the view. Optionally, if the email is urgent, it is flagged accordingly with a red exclamation point; or if the sender used a mood stamp, you see an emoticon. All this information helps you immediately to get a rough idea of the email content. However, the same email may have different meanings for different recipients: For some recipients, the email may contain a to do item, whereas for other recipients, the very same email may just be informative, an FYI. For the first group of recipients, the email is usually more important and more time critical, so it deserves more attention.

Most mail systems already support this distinction-and so does Notes-by offering different roles for receivers: the so-called To: list (recipients who are supposed to respond to this mail or perform another action) and the so-called cc: list (recipients who need to take notice, but who do not need to respond immediately to this email). Unfortunately, the different recipients of one email cannot see this difference--and their individual role--from the Inbox. Instead, each user, whether on the To: list or on the cc: list, must open or preview the email to see on which list he or she is listed. When looking at the content, the user has to parse the To: list and/or the cc: list manually to recognize his own user ID in one of these lists.

Using different methods, this article describes how to implement a solution that analyzes each mail message and displays an icon in your Inbox to indicate whether you are in the To:, cc:, or bcc: field of an email, or in an email distribution list. This helps you to better determine the relevance of an email and to prioritize your messages. For those of us who receive more email than we know what to do with, this solution can help to significantly reduce the amount of time spent sorting through emails, so you have more time to spend on important emails. Even if you don't receive an overwhelming number of emails, this solution can help you to focus on the right mail first. And if you're like most of us, you check your email to see what's been addressed to you only, and then return to it later to thoroughly read the message. If that's the case, this solution can eliminate the step of checking to see who is listed in the To:, cc:, or bcc: fields.

This article is an expanded version of a tip that we recently published, "Marking incoming mail." Familiarity with the Notes formula language is helpful, but not required.

User's view

The implementation described in this article distinguishes six scenarios and assigns one of six different icons to each new mail document to indicate which of the scenarios applies to you. Here they are:

• You are the only recipient in the To: list.
• You along with other users are in the To: list.
• You are not in the To: list, but are the only recipient listed in the cc: list.
• You are not in the To: list, but are listed together with other users in the cc: list.
• You are neither in the To: list nor in the cc: list, but in the bcc: list.
• You are not explicitly listed in the To: list, in the cc: list, or in the bcc: list, but are part of a distribution list.

The following screen shows the icons assigned to each of these scenarios. The Subject column describes each of the icons.

Note: This solution does not affect your Subject field.

In contrast to other flags (FYI, urgent) and other information (sender, subject), the icon is individually computed for each email recipient, so the same email may look different for different recipients.

Back to top

Implementation overview

You have three options for implementing the solution in Notes:

• Create a server-based agent, the Mark incoming mail agent, that runs in your mail database.
• Modify your mail template.
• Create a private view.

In the following sections, we describe each implementation and the prerequisites for implementing each option.

Mark incoming mail agent

In this implementation, an agent, which we call the Mark incoming mail agent, resides on the Domino mail server and is triggered whenever a new mail document arrives. Once triggered, the agent determines the mail database owner's role (To:, cc:, bcc:, or distribution list) with respect to the document and assigns an integral value representing the appropriate icon to the _ViewIcon variable that is part of the mail document. Without further modifications to the Domino mail server or the Notes client, you use the existing infrastructure to display icons. This infrastructure is used to graphically mark invitations, counter-proposals, and other invitations responses; but for regular email, it is largely unused (with one exception: the rare use of the mood stamp feature).

Prerequisites

Before you proceed with this implementation, make sure you meet the following prerequisites:

• You must have permission to define a shared agent for your mail database.
• You must have permission to run a shared agent for your database on the server with the trigger Before New Mail Arrives.
• You cannot have another active agent using the trigger Before New Mail Arrives running on the server copy of your database.

If you do not know whether or not you meet the prerequisites, follow the instructions at your own risk and watch for error messages described in the section "Troubleshooting."

To create the agent in your database, use your Notes client. Unless you want to modify the agent, you do not need Domino Designer. (If modifications are required and you do not have a Designer client, delete and re-create the agent.)

Creating the Mark incoming mail agent in Notes 5

Use a server replica or copy of a mail database (and not a local replica or copy) for this agent.

1. In Notes 5.0.x, open the server replica or copy of a mail database.
2. In the Inbox view, choose Create - Agent.
3. In the Agent Properties box, enter Mark incoming mail as the agent name.
4. Select the Shared Agent option.
5. In the When should this agent run field, select the Before new mail arrives option.
6. Click the Add Action button.
7. In the Action field, select the @Function Formula option.
8. Accept the default option "Update existing document when run."
9. In the Formula window, add the following code:
   
   

   REM "============Assign the icon numbers"; TO1:=3; TO2:=4; CC1:=22; CC2:=21; BCC:=163; DISTR:=70; userName:=@ProperCase(@DbTitle); REM "============Do not change anything beyond this line"; FIELD _ViewIcon:=_ViewIcon; tmpvar:=@If( _ViewIcon!="" & _ViewIcon!=0;0; @IsDocTruncated; 0; @ProperCase(@Name([CN];SendTo)) = userName; @If(@Elements(SendTo)=1; TO1; TO2); @ProperCase(@Name([CN];CopyTo)) = userName; @If(@Elements(CopyTo)=1; CC1; CC2); BlindCopyTo != ""; BCC; SendTo+CopyTo != ""; DISTR; 0); @If(tmpvar = 0; ""; @SetField("_ViewIcon";tmpvar));

   
   
   
   
10. Click OK when done.
11. Save and close the agent.

Creating the Mark incoming mail agent in Notes 6 and later

Use a server replica or copy of a mail database (and not a local replica or copy) for this agent.

1. In Notes 6.x, open a server replica or copy of a mail database.
2. In the Inbox view, choose Create - Design - Agent or Create - Agent depending on your menu options.
3. In the Agent Properties box, enter Mark incoming mail as the agent name.
   Figure 2. Agent Properties box
   
   
4. Accept the default Shared option.
5. In the Runtime field, select Before new mail arrives and close the Properties box.
6. Keep the default Simple Actions option selected and click the Add Action button.
7. In the Add Action dialog box, select the @Function Formula option in the Action field. Accept the default "Update existing document when run" option.
8. Add the code above to the Formula window.
9. Click OK when done.
10. Save and close the agent.

More information about the Mark incoming mail agent

After you create and use this agent to help process your emails, you may be surprised that the whole functionality is done using only 25 lines of code. This is due to the powerful Notes infrastructure. When you move an email from the Inbox to another folder, the icon is still visible. However, only mail documents that arrive after you create the agent are marked.

Note: Some older mail templates do not display the _ViewIcon variable for urgent mail documents, but rather show an exclamation point instead. This is fixed in newer mail templates.

The comments in the code describe the agent in more detail (comments beginning with // are not valid comments in the macro language):

TO1:=3; 	// Numeric code of icon shown for "The only user on To:"
TO2:=4; 	// Numeric code of icon shown for "User with others on To:"
CC1:=22; 	// Numeric code of icon shown for "The only user on cc:"
CC2:=21; 	// Numeric code of icon shown for "User with others on cc:"
BCC:=163; 	// Numeric code of icon shown for "User on bcc:"
DISTR:=70;	// Numeric code of icon "User not found explicitly 
			// Ddistribution list assumed"

// Because the code runs on the server, there is no
// easy way to find out the user ID (because in Domino 6, @UserName
// returns the server name rather than the user ID).
// The heuristics to use the name of the database is a good start.
// The @ProperCase is just a way to ignore the case in the To:/cc: fields later.
userName:=@ProperCase(@DbTitle); 

// The "FIELD" statement is necessary to make all
// changes of this variable persistent to the document.
FIELD _ViewIcon:=_ViewIcon;

tmpvar:=@If(			// This tmp variable receives the computed value.
_ViewIcon!="" & _ViewIcon!=0;0; 	// If an icon is already attached, do nothing.

// If doc is truncated (due to 40K replication limit), do not change it.
// Otherwise, the truncated version could be replicated back and 
//  truncate the document on the server.
@IsDocTruncated; 0;

// Search case-normalized user ID in the To: list and assign icon TO1 or TO2
@ProperCase(@Name([CN];SendTo)) = userName; @If(@Elements(SendTo)=1; TO1; TO2); 

// Search case-normalized user ID in the cc: list and assign icon TO1 or TO2
@ProperCase(@Name([CN];CopyTo)) = userName; @If(@Elements(CopyTo)=1; CC1; CC2); 

// If the bcc: list is not empty, only the user's own user ID can be there 
//  because by definition, users do not see other bcc users.
BlindCopyTo != ""; BCC;

// User ID not found in each of the lists - distribution list assumed;
//  Guessing is all we can do at this time: When both To: and cc: 
//  contain a value, either could be a distribution list containing 
//  the user's user ID. 
SendTo != "";  DISTR; 	
0);				// Default case: assign 0 (which will be a no-op)
@If(tmpvar = 0; ""; @SetField("_ViewIcon";tmpvar)); // Make value persistent (unless 0)

Troubleshooting the Mark incoming mail agent

Here are some known issues in which users could not get the agent up and running.

Insufficient permission

Depending on which permission your server's administrator gave to you, you may not be authorized to create an agent to run on the server. If you are not authorized, you receive a message like the following:

If your administration will not grant you the necessary permission, don't worry--you may be able to use the client-based mail template implementation instead.

All mail documents are marked with the same icon

If your user ID does not match the name of the mail database, your Inbox shows all mail documents with the distribution list icon (see Figure 1).

In this case, you can replace the following line in the code:

userName:=@ProperCase(@DbTitle);

with this line:

userName:=@ProperCase("myUserid@myNode");

For example:

userName:=@ProperCase("Andreas Arning/Germany/IBM");

or the longer version:

userName:=@ProperCase("CN=Andreas Arning/OU=Germany/O=IBM@IBMDE");

Not sure which string to use for myUserid@myNode? Do the following:

1. Open your Inbox.
2. Right-click a document for which you know you are the only user on the To: list.
3. Choose Document Properties from the menu.
4. Click the Fields tab of the Document Properties box to display the variables.
5. In the left window, select the SendTo variable. Your user ID displays in the right window.

Some messages in which you are the only user on the To: list are marked with the icon for distribution list

There are cases in which multiple user ID strings are used for the same user ID. For example, both the internal user ID John Denver/US/IBM and the external user ID JohnDenver@us.ibm.com could both represent the same user. However, in the program code shown previously all comparison is done against only one of these strings. To make your alternate user ID known to the system (in this example, JohnDenver@us.ibm.com), instead of the program code shown earlier, use the following code instead:

REM "============Assign the icon numbers";
TO1:=3;
TO2:=4;
CC1:=22;
CC2:=21;
BCC:=163;
DISTR:=70;
userName:=@ProperCase(@DbTitle);
altUserName:=@LowerCase("JohnDenver@us.ibm.com");
REM "============Do not change anything beyond this line";

FIELD _ViewIcon:=_ViewIcon;

tmpvar:=@If(
_ViewIcon!="" & _ViewIcon!=0;0;
@IsDocTruncated; 0;
@ProperCase(@Name([CN];SendTo)) = userName; @If(@Elements(SendTo)=1; TO1; TO2);
@ProperCase(@Name([CN];CopyTo)) = userName; @If(@Elements(CopyTo)=1; CC1; CC2);
@LowerCase(SendTo) = altUserName; @If(@Elements(SendTo)=1; TO1; TO2);
@LowerCase(CopyTo) = altUserName; @If(@Elements(CopyTo)=1; CC1; CC2);
BlindCopyTo != ""; BCC;
SendTo+CopyTo != "";  DISTR;
0);
@If(tmpvar = 0; ""; @SetField("_ViewIcon";tmpvar));

Occasionally messages are not marked at all

There have been cases in which the icons have been assigned properly for weeks, but now and then, some messages do not receive icons, although the To: list was filled properly. It may be that the threshold in the mail server for the amount of CPU dedicated to agents has been reached. This threshold can be considered as fuse to protect the system against unintended overload caused by a broken agent (which consumes CPU excessively due to a programming error in the agent code).

To resolve this problem, you can either contact the server administrator and ask her to increase this threshold or consider using one of the alternate implementations described later in this article.

Unexpected warning during agent creation

You may receive a warning similar to the following when you try to save the newly defined agent:

This warning occurs if you define a server-based agent on a local replica or copy of your mail database. When you replicate the local mail database with your mail server, it's determined if the permission on the server are sufficient. However, when you replicate, there are no error messages and warnings about permission because replication is usually done in the background, so the agent may or may not run, depending on the server permission.

To determine if you have sufficient permission, use a server replica or copy of your mail database.

Only one agent may run before mail arrives

If you already have an agent running with the trigger Before new mail arrives, it may not be possible to run this agent with the same trigger because of system restrictions. In this case, you may want to know whether or not you can run the agent after new mail has arrived. Before doing so, keep in mind that when an agent runs with the trigger After new mail arrives, the scheduled run of the agent may be delayed for several minutes after arrival of the mail. This has the following consequences:

• Occasionally, you may see emails that are not marked with an icon; the next time you replicate the same email suddenly has an icon.
• When changing mail on your local replica which is not yet marked, you may run into replication conflicts later because the server may change the server-based copy of the same document at the same time to add the icon.
• When deleting a mail document that is not yet marked, the server may find itself in an inconsistent state. It wants to run against a certain document, but the document is missing. You may need to uninstall and reinstall the agent to recover.

For these reasons, we don't recommend the trigger After mail has arrived for this agent.

Another fallback solution is to run the agent on a client copy or replica instead. Before doing so, keep in mind the consequences:

• All incoming documents are touched on the local copy or replica. This means that for all incoming mail messages, the client copy is considered the most recent version and is replicated back to the server again.
• Documents that are truncated due to the 40K replication option are not touched by the agent (to avoid a potential problem in which the truncated document is considered the most recent version and replaces the entire document at next replication). For truncated documents you do not receive any icons.

Instead, you may want to try the mail template-based version.

Mail template implementation

If the Mark incoming mail agent is not suitable for you (because you don't meet the prerequisites above), you can use an alternate implementation. The alternative implementation modifies your mail template.

Prerequisites

For this option, you must meet the following prerequisites:

• You must have Domino Designer installed.
• You must have permission to modify the mail template.

If you do cannot or do not want to overwrite the mail template, or if you do not have Domino Designer installed, you can still create a private view that shows you the same icons. This article describes how to create a private view in the section "Creating a private view to display icons."

Modifying the mail template

Use any replica or copy of your mail database. If you use a local database, make sure to replicate the changes to the server to take effect.

1. In Domino Designer, open a server replica or a local copy of a mail database.
2. In Folders, select the ($Inbox) folder.
3. Right-click and select Edit.
4. Accept the warning that your changes will be lost when the template is refreshed.
5. Collapse the view.
6. Select the Untitled column that appears before the Who column. This Untitled column contains _ViewIcon variable in the formula. Check the Programmer's Pane for the variable.
7. At the beginning of the formula, add the following lines:
   
   

   REM "============Assign the icon numbers"; TO1:=3; TO2:=4; CC1:=22; CC2:=21; BCC:=163; DISTR:=70; userName:= @ProperCase(@Name([CN];@UserName)); tmpvar:=@If( DeliveredDate = ""; 0; @ProperCase(@Name([CN];SendTo)) = userName; @If(@Elements(SendTo)=1; TO1; TO2); @ProperCase(@Name([CN];CopyTo)) = userName; @If(@Elements(CopyTo)=1; CC1; CC2); BlindCopyTo != ""; BCC; SendTo != ""; DISTR; 0);

   
   
   
   
8. Scroll down in the formula and find the last occurrence of the following two lines:
   
   @IsAvailable(_ViewIcon);
_ViewIcon;
   
   
9. Immediately after these two lines, add the following line:
   
   tmpvar != 0; tmpvar;
   
   
10. Save and close the ($Inbox) folder.

Open your Inbox in Notes to see your changes.

More information about modifying the mail template

This implementation shows icons for all mail documents in your Inbox, including those that arrived before you changed your mail template; however, when you move an email from the Inbox to another folder, or if you look at an email using another view, the To:/cc: icon is no longer visible. If you want the icon to appear in other views and folders in your mail database, make the same modification for those views and folders.

In some older mail templates, the urgent mail icon (exclamation point) is shown instead of any _ViewIcon. This is done in the following code sequence in the template:

...
Importance = "1";
    150;
@IsAvailable(_ViewIcon);
     _ViewIcon;
...

Here are explanations for these code lines:

...					// Surrounding @if structure with multiple conditions
Importance = "1";	// Test condition: if variable "Importance" equals "1" ...
    150;				// ... then show icon #150 ( ! )  and stop
@IsAvailable(_ViewIcon); 	// Next test condition: whether var _ViewIcon exists 
     _ViewIcon;		// If yes, show _ViewIcon and stop 
...					// further conditions

If you prefer to see the To:, cc:, or bcc: icons for urgent mail as well (instead of the exclamation point), you can reorder the statements in the code to the following order:

...
@IsAvailable(_ViewIcon);
     _ViewIcon;
Importance = "1";
    150;
...

Then, insert the line mentioned above in the middle of these lines:

...
@IsAvailable(_ViewIcon);
     _ViewIcon;
tmpvar != 0; tmpvar;
Importance = "1";
    150;
...

You may even decide to show the computed icon even if a view icon already exists, for example, to avoid abusing the view icon (see below). In this case, add the variable responsible for displaying the computed icon as the first of these five lines:

...
tmpvar != 0; tmpvar;
@IsAvailable(_ViewIcon);
     _ViewIcon;
 Importance = "1";
    150;
...

Once you have modified your ($Inbox) folder, you can enable your Inbox to sort these icons. Edit the column properties for the Untitled column. Select the Sorting tab and choose the "Click on column header to sort" option. This allows dynamic sorting by icons in the Inbox by clicking the little arrow in the column header, so for instance, all documents having only your user ID in the To: list are grouped together.

As mentioned earlier, the implementation takes advantage of the existing Domino/Notes infrastructure by reusing conventions for the _ViewIcon variable. The implementations shown so far do not modify the appearance of mail documents that already have the variable _ViewIcon defined. The disadvantage of this approach is that any one aware of the mechanism and the semantics of the icons could abuse this feature, for example, sending an email via distribution list, but adding a _ViewIcon variable set to value TO1.

To avoid this problem, use one of the following refinements:

• When an incoming mail document has the _ViewIcon variable already set to one of the values used in the above code (that is, the values TO1, TO2, CC1, CC2, BCC, DISTR), then the value is overwritten as if it did not exist.
• Any existing values of _ViewIcon are ignored. (Caveat: Icons indicating invitations do not appear when you use this refinement.)
• The icon computed by the above code is displayed as separate column. This is explained in more detail in the following section.

Creating a new column

If you do not want to modify the existing Untitled column for _ViewIcons and want to create a new dedicated column for these icons, follow these steps:

1. In Domino Designer, open a server replica or a local copy of a mail database. (If you use a server replica, make sure to replicate the design also.)
2. In Folders, select the ($Inbox) folder.
3. Right-click and select Edit.
4. Accept the warning that your changes will be lost when the template is refreshed.
5. Collapse the view.
6. Create a new column.
7. Set the size of this column to 1
8. Select the Display values as icons option.
9. Deselect the Resizable option
10. In the column value field, select the Formula option.
11. Replace the line: @DocNumber (which is inserted as default code snippet) with the following code snippet:
    
    

    REM "============Assign the icon numbers"; TO1:=3; TO2:=4; CC1:=22; CC2:=21; BCC:=163; DISTR:=70; userName:= @ProperCase(@Name([CN];@UserName)); @If( DeliveredDate = ""; 0; @ProperCase(@Name([CN];SendTo)) = userName; @If(@Elements(SendTo)=1; TO1; TO2); @ProperCase(@Name([CN];CopyTo)) = userName; @If(@Elements(CopyTo)=1; CC1; CC2); BlindCopyTo != ""; BCC; SendTo != ""; DISTR; 0);

    
    
    
    
12. Save the formula.
13. Optionally, enable the sort function as described earlier. Save and close the ($Inbox) folder.

If you want to change other folders and views in addition to or instead of your Inbox, follow the same instructions.

Creating a private view to display icons

If you are not allowed or do not want to customize the Inbox, or if you do not have Domino Designer installed, you can still benefit from a solution to create and customize a private view similar to the All documents view.

1. In your Notes client, open the Inbox view.
2. In Notes 5.0.x, choose Create - View. In Notes 6 or later, choose Create - Design - View.
3. In the View Name field, enter Show Documents Marked (or any name of your choice).
4. In the View Type field, select Private.
5. Click the Copy from button, and select All Documents.
6. In the Selection conditions window, add the following line:
   
   SELECT (DeliveredDate != "")
   Figure 5. Defining a private view
   
   
7. Click Customize.
8. Collapse the view.
9. Of the Untitled (Column), select the one that has _ViewIcon in the formula part.
10. Add the following lines to the beginning of the formula:
    
    

    REM "============Assign the icon numbers"; TO1:=3; TO2:=4; CC1:=22; CC2:=21; BCC:=163; DISTR:=70; userName:= @ProperCase(@Name([CN];@UserName)); tmpvar:=@If( DeliveredDate = ""; 0; @ProperCase(@Name([CN];SendTo)) = userName; @If(@Elements(SendTo)=1; TO1; TO2); @ProperCase(@Name([CN];CopyTo)) = userName; @If(@Elements(CopyTo)=1; CC1; CC2); BlindCopyTo != ""; BCC; SendTo != ""; DISTR; 0);

    
    
    
    
11. Scroll the formula and find the last occurrence of the following two lines:
    
    @IsAvailable(_ViewIcon);
_ViewIcon;
    
    
12. Immediately before these two lines, add the following line:
    
    tmpvar != 0; tmpvar;
    
    
13. Save the formula and the view.

The first time you open this view may take some time, depending on the size of your mail database.

See the section "More information about modifying the mail template" and the Customization sidebar to find hints about customizing the view to your preferences and needs.

Back to top

Conclusion

In this article, we described a new Notes agent for providing a faster and better overview of your incoming mail. This agent adds an icon indicating your role in each email message that you receive in the Inbox view. We provide three different techniques for our solution: the server-side agent, mail template modification, and creation or customization of a private view.

Resources

• Marking incoming mail
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• User's view
• Implementation overview
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into Lotus on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers