IBM Support

The enhanced unread functionality in Notes/Domino

Technote (FAQ)


Question

How do you set up and use the enhanced unread functionality? This function was introduced in Notes/Domino 6.0.3 and 6.5 and is available in 6.x and later releases.

Answer

In Notes/Domino 6.0.3 and 6.5 and later, additional functionality has been introduced to provide replication of unread marks.

Note: In order for this feature to function, both servers and clients must be running at least 6.0.3 or 6.5.

Below are details on the basic functionality and troubleshooting tips. The descriptions below are based on server-to-server replication, but the functionality is the same with client-server replication.

Basics:
An Unread Activity Log is kept which is then used to update the Unread Table (The design of the Unread Table has not changed; it is still used to denote Unread documents.). Both the log and the table are stored in the database. The log contains time stamp information that is used to determine the latest unread status for a document. When a user marks a note read or unread, a new entry will be added to the end of the activity log. The activity log is played back when a database is opened or F9 is pressed while in a view. The feature will only have an effect on the unread status of documents after it has been enabled (The feature will not log the status of pre-existing documents until they have been marked as unread or read after enabling the feature.). The feature requires using the ODS (On Disk Structure) of 43.

For efficiency and performance, this feature is best suited to applications with few users, such as mail databases. While it will function in applications that are used by many users and experience high activity, a performance impact is likely.

The functionality is designed to work with iNotes as well as standard Notes mail. Unread mark updates that occur on pre-6.0.3/6.5 Notes/Domino servers and clients will not be integrated into the Unread Activity Log.


Unread Activity Log Playback (which updates the Unread Table):
During the playback, the Unread Table is brought up to date with the activity log. Playback starts from the oldest modified log entry since playback. During playback, the sequence number in the log entry is compared with the sequence number of the note in the database. If the note has been deleted, or the sequence number of the note is later than the sequence number of the entry, then the activity is ignored. Otherwise, the NoteID is either added or removed from the Unread Table. The playback of the log is optimized by the use of a pointer that indicates the oldest log entry added since the last replay. The log will be purged of entries older than the replication time limit (replication cutoff time).

Note: For optimization, the log is sorted from the last entry to the first entry.


Enabling the feature:
The feature is enabled via an Advanced Database property. The "Replicate unread marks" property can be enabled for "Clustered servers only", "All servers" or the default "Never". Note: In order to enable the feature for local replicas select the "All servers" option.

Note: If the properties are not listed then make sure that the database is using a ODS version of 43. This can be checked by using the menu: File -> Database -> Properties -> "i" (info) tab.

Ways of enabling/disabling the property are:

  • Use File > Database > Properties to enable the property.
  • Use the Administrator client to select multiple files, and then using Advanced Properties, enable the property.
  • Set the property in the template and then Replace the design (or Refresh design when first set). Note: Once this property has been set, it will no longer inherit the property from the template with a design refresh; only with a design replace will the template property be inherited after the database has been initially set. For details, see "Which Database properties are affected by a Design Replace or Refresh" (#1176010).
  • Run the Compact task with the -u switch.

Additionally:
  • Make sure that the Advanced Database property (on the beanie tab) "Don't maintain unread marks" is not enabled. The property can either be manually unchecked or unchecked by running the Compact task with the -u switch.
  • It is also recommended that the Database property on the Designer tab "Do not mark modified documents as unread" be enabled. Note: The functionality will operate with this property disabled but it may lead to confusion regarding whether the functionality is operating as expected. See the Troubleshooting section below for additional details.
  • Previous releases used the client NOTES.INI parameter REPLICATOR_SYNC_UNREAD to ensure the exchange of unread marks in Client - Server replication. The use of this parameter should not have any effect on the new functionality - it will be ignored when replicating databases that have the "Replicate unread marks" property enabled. Thus, the parameter can be left in the INI if needed for applications that reside in a mixed environment and cannot make use of the new functionality. If the parameter is unneeded, then it is best to remove it to avoid a short performance slowdown initially during local replication.

Note: If the property was enabled by inheritance from a template (when the database was created or via design replace) and the database replicates with a Domino server prior to 6.0.3, then the property will be disabled on the pre-6.0.3 replica. In this case, once this replica replicates with other servers, regardless of their release, the property will be disabled on those replicas as well, except in the case where the property was enabled using the Notes Client or Admin Client.


Additional Details on Operation:
How server time discrepancies are accounted for in the log:
The Unread Activity Log entries include a time stamp portion that will be used to determine which unread status of the document was performed last. The functionality to sync the Unread Tables between two replicas will also include a time-skew value that represents the time discrepancy between two servers (because like snowflakes, no two servers time settings are exactly the same). This time-skew value will then be used when performing the calculations to determine which unread status for a document was the latest. The time-skew is calculated each time the activity is replicated, the time of the source server is replicated to the target server immediately prior to the exchange of the activity log information.

Performance optimization:
The whole Activity Log does not replicate each time -- only the latest updates. Also a bounceback prevention mechanism is designed into the functionality. For each unread entry in the unread log, information is stored to record which server supplied the information. When the log is replicated back to that server, it excludes the entries that originated from that server. This prevents replication bounce-back (replicating information back to the server where the information originated).

If we detect a first-time replication, we send the entire unread log for all users of this database to the new replication server. This populates the new server with the current log. In workstation-initiated replication involving local replicas, only the requesting user's unread log will be replicated - other user's unread logs will not be replicated.


To ensure that new replicas reflect the expected unread status:
When using the new unread replication functionality, it is expected that new replicas will only reflect unread activity which occurred after the feature was enabled. If the new functionality is not enabled, the previous Unread Journal functionality will work as designed, and when you create a new replica the replica will display documents with the expected unread status.

If you have not enabled the new unread replication functionality:
Create any desired new replicas prior to enabling the new functionality. The Unread Journal will preserve the unread status in the new replica. Once the replica is created, enable the new unread replication functionality. The feature is enabled using an Advanced Database property. The "Replicate unread marks" property can be enabled for "Clustered servers only", "All servers" or the default "Never".

Note: In order to enable the feature for local replicas select the "All servers" option.

If you already have had the unread replication functionality enabled:
Synchronize the replicas by updating the unread/read status of all the documents in the database to write them to the Unread Activity Log. This involves toggling the documents' unread status to the opposite status. Then, toggle documents a second time back to the original state.

Steps:
  1. Create two folders, Group1 and Group2.
  2. Go to the All Documents view.
  3. From the menu, select: Edit -> Select All.
  4. If using a mail based design, click the Action Bar -> Folder -> Move to Folder -> select Group1 -> Add. For other designs, drag the document collection to the Group1 folder in the left pane.
  5. Switch into the Group1 folder.
  6. From the menu, select View -> Show -> Unread Only. Only the unread documents should appear.
  7. From the menu, select Edit -> Select All.
  8. If using a mail-based design, click the Action Bar: Folder -> Move to Folder -> select Group2 -> Move. For other designs, drag the document collection to the Group2 folder in the left pane.
  9. From the menu, select View -> Show -> Unread Only. The read documents should re-appear.
  10. From the menu, select Edit -> Select All.
  11. From the menu, select Edit -> Unread Marks -> Selected Unread.
  12. From the menu, select Edit -> Select All.
  13. From the menu, select Edit -> Unread Marks -> Selected Read.
  14. From the menu, select Actions -> Folder Options -> Remove folder.
  15. Switch to the Group2 folder.
  16. From the menu, select Edit -> Select All.
  17. From the menu, select Edit -> Unread Marks -> Selected Read.
  18. From the menu, select Edit -> Select All.
  19. From the menu, select Edit -> Unread Marks -> Selected Unread.
  20. From the menu, select Actions -> Folder Options -> Remove folder.


Troubleshooting:
As noted above, the feature is designed to work regardless of whether the "Do not mark modified documents as unread" property is enabled or not. In order to troubleshoot a suspected failure of the feature it is suggested that this property be enabled to ensure that a document is not being marked as Unread relative to a modification rather than user interaction. For example, with this property disabled, if an agent acts on a document, this will cause the document to become Unread and if a user were not aware that an agent had modified the document they may assume that the feature was not functioning correctly. If the property is not enabled, and the Notes Domino 6.5 Mail Memo Followup feature is being used, followup documents will be marked Unread once the followup has been performed.

Previous releases used the Unread Journal to synchronize unread marks. It is a fixed-size journal, stored in the desktop, that records and then attempts to replay a users unread activity for a database when the user switches to a new replica. The journal will override the activity log if the journal thinks it has more current information. This will typically occur in cases where a user is setting the Unread status of documents from more than one client. If the Unread status of documents in a replica are not as expected, it is recommended that the journal be disabled to determine if this is the cause. To disable the unread journal playback for databases that support unread replication, the following can be added to the client NOTES.INI:
      DEBUG_LIMIT_UNREAD_JOURNAL=1

Note: The above INI will have no effect on the operation of Unread Journals for databases that do not have the unread replication feature enabled.

If a server has experienced server time creep that was greater than 24 hours, then there is the potential for discrepancies in the User Activity Log once the server time has been corrected. It is therefore recommended that time creep not be allowed to extend beyond 24 hours before being corrected. If this should occur, and there is a discrepancy on the server's replica, the recommended solution would be to first attempt to resolve by clearing the replication history and replicating, and if that does not resolve, then to pull a fresh replica from another server.

If the unread tracking property should become disabled, investigate whether the database replicates with a Notes Domino server running a release prior to 6.0.3. If the database replicates with a Domino server prior to 6.0.3, the property will be disabled on the pre-6.0.3 replica. Once this replica replicates with other servers, regardless of their release, the property will be disabled on those replicas except in the case where the property was enabled using the Notes Client or Admin Client.

Recall that Unread mark updates that occur on pre-6.0.3/6.5 servers will not be integrated into the Unread Activity Log. If unread mark activity is not as expected, make sure that the activity did not occur on a failover server running a release prior to 6.0.3 or 6.5.

Note: Unread activity will not replicate as expected to a local replica if the updated activity occurred on a second local replica and both local replicas are based on the same OS copy of the database. For example, on client A you make an OS copy of your mail file and transfer it to client B. When you update documents on the client A replica, and then replicate to a server C replica, the unread updates work as expected. When you then replicate from server C to client B, the client A updates do not appear on the client B replica as expected. This occurs because with local replicas the creation date of the database is used to identify it to prevent unread activity from being transferred back to the same system. This functionality is referred to as 'bounceback prevention' in the "Performance Optimization" paragraph within the "Additional Details on Operation" section above.

Note: The functionality has been observed to fail under specific conditions with the result that local unread activity may not be reflected in a server replica. The issue only appears to occur with databases based on Notes templates and in cases where unread activity has taken place in the local replica and not the server replica.


Supporting Information:
There is no attempt to delete previous activities in the log for a document (note) so it is possible that a note has multiple entries in the log. The log is purged of data based on the replication cutoff setting ("Remove documents not modified in the last..." property in the database's Replication Settings). Each entry in the Unread Activity Log is 60 bytes. An entry occurs each time a user marks or unmarks a document as Unread. The time stamp noted in the log is specific to 1/1000 of a second (a tic).

Additions to the Unread Activity Log are made to the in-memory copy, which is then written to the on-disk copy. If anything should interrupt this transfer process the internal notations within the log will note this and the log will be rebuilt in-memory and then written to disk.

If log corruption is detected during Fixup, this will set a flag that will request a "Full Unread Replication" of the activity log during the next replication. During the next replication the corrupt log will be fully compared with the log from the second replica and any incorrect data will be updated.

New documents are written into the Unread Table but not the User Activity Log. A document is not written into the activity log until it is marked as read or unread.

Document information

More support for: IBM Notes

Software version: 8.0, 8.5, 9.0

Operating system(s): Windows, iOS

Reference #: 1140018

Modified date: 15 September 2009


Translate this page: