In Xing's Notes/Domino forum a "Problem bei Feldreplikation im Cluster" (problem in field replication in a cluster) has been described. I want to take this occasion to post a long planned blog entry about the "mechanics" of replication.

When a Notes client or Domino server starts a replication with a(nother) server, first a Notes database with the same replica id on there is searched. You find the replica id of a database on the second tab in the database properties box:

If the server finds a replica of the database, it looks for a log entry in the replication history of each of the servers. It uses this to determine a cutoff date prior to which it knows that the databases were synchronized.. If there is no history for this particular pair of servers, the complete lists of documents on both sides get compared. For each document in one database, the corresponding document - i. e. a document with the same unique id - in the other database is searched for. If a replication history entry exists, only documents created, modified or deleted after the last replication are used for this step.

After this there are three lists:

• documents only in one database
• documents only in the other database
• documents in both sides.

If a document exists only on one side,
it's easy: Simply create a copy of this document on the other side. When
it exists on both sides, it's a little more complicated. But for this case,
Lotus had some good ideas:


Each document has a sequence number.
When a document gets saved the first time, its sequence number is 1. After
that, the sequence number is increased by 1 each time, the document is
saved. You can find the sequence number of a document on the sixth tab
in the document properties box - as a hexadecimal number in the third row
after the hyphen:



This document has been saved for 0x19
= 25 times.


Additionally to the documents, each
single item has a sequence number, too. When you select a field name in
the left side list on the second tab of a document's properties, the details
of this item are displayed on the right side - in between the sequence
number of the item, but as a decimal number.






As described earlier, when a document
gets saved for the very first time, it self and all of its items get the
sequence number 1. When it got edited later on and saved again, its sequence
number is increased by 1. Furthermore, each item is checked, if it has
been changed since the last save. If it hasn't been changed, everything
keeps the same - including it's sequence number. But if it has been modified,
it gets the current sequence number of the document as sequence number.
The screen shot above means that the item EntryHTML has been changed, when
the document has been saved for the 25th time - and not, that this item
has been changed 25 times.


In addition each document is timestamped
on each edit. The most current modification/creation time is displayed
on the first tab of the properties window and is an internal property of
the document. A historical record of modification times is stored in the
$Revisions item and the list of NotesNames, of who has changed and saved
the document, is stored in the $UpdatedBy item.


All of this information together is
used by the replicator to determine, where which modifications has been
done and if a replication conflict has occurred. Normally if the document
has been edited on both servers since the last replication there will be
a replication conflict. If "Merge Conflicts" is selected in the
form - and therefore there is a $ConflictAction of the value "1",
whether there is a conflict or not is determined at the field as opposed
to the document level. The replicator uses the sequence numbers of the
items to determine what gets merged into the resulting document. If the
same field has been edited on both sides of the transaction there will
be a conflict in this case as well. Conflicts are created by adding a $Conflict
item to one copy of the document.


Special case: deleted documents

If a documents gets deleted, it should
certainly not be revived at the next replication. But how should the replicator
distinguish documents deleted from this side from documents created on
the other side? Therefore, when a document gets deleted, a so called deletion
stub is created - essentially containing the universal id of the deleted
document. When the replicator finds a deletion stub, it simply deletes
the document from the other replica.


Update:

Rob Axelrod, Vice-President of Technotics,
Inc. kindly reviewed this post
and helped me to clarify some points (and enhance the style).


Update 2:

There seems to be an error with $ConflictAction
and the Merge Conflicts setting since version 6.5.1. For details and links
to technotes see:

Is
IBM Lotus asleep at the wheel? What is up with $ConflictAction???,
Lord
Lotus Blog