Domino Upgrade

VersionSupport end
Upgrade to 9.x now!
(see the full Lotus lifcyle) To make your upgrade a success use the Upgrade Cheat Sheet.
Contemplating to replace Notes? You have to read this! (also available on Slideshare)


Other languages on request.


Useful Tools

Get Firefox
Use OpenDNS
The support for Windows XP has come to an end . Time to consider an alternative to move on.

About Me

I am the "IBM Collaboration & Productivity Advisor" for IBM Asia Pacific. I'm based in Singapore.
Reach out to me via:
Follow notessensei on Twitter
Amazon Store
Amazon Kindle
NotesSensei's Spreadshirt shop

« Avoiding login prompts in mobile approvals | Main| Explaining web enablement challenges to business users »

What to do with Save & Replication conflicts

QuickImage When customers start developing new Domino applications, the distributed nature of Domino can pose a stumbling block. Suddenly the unheard of replication conflict crops up and wants to be dealt with. A customer recently asked:
"I need to check with you about the Conflict Handling in Lotus Notes application. Default I will set the Conflict Handling to Create Conflicts, but I found my application have create more and more replication or save conflict documents. What can I do for all these replication or save conflict documents, and I found some information in conflict documents is not in original document? How can I prevent the system to generate conflict document?"
Replication Conflict Handling
Before going into details, lets have a closer look how Notes handles its data. There's quite some hierarchy involved:
  1. to replicate two databases need to have the same replica id. The replica id is created when a database is created and only can be changed using the C API (or a wrapper around it). When a NSF is copied on the file system, you actually create a replica (but you wouldn't do that, would you?
  2. Inside a database 2 documents need to have the same document unique id (UNID), which is created from a time stamp at document creation time. The UNID is actually read/write in LotusScript and Java and a certain gentleman can teach you about creative abuse of this capability. In addition in the document properties a sequence number is stored that gets incremented when a document is changed. Together with the last modification date this forms the patented Notes replication.
  3. Inside the document the Notes items are stored. This are not just field values in a schema (like in an RDBMS) but little treasure troves of information. An item has a name, an array of values, a data type, an actual length and a sequence number. Notes can (and does) use this sequence number to see what items have been altered (note the difference: a form contains fields, a document contains items)
So how do the form options behave for conflicts (which are stored as $ConflictAction item in the document)? First Notes determines a "winner" and a "loser" document. The winner is the most edited document. If there same amount of edits, only then the document saved last wins (savour this: an older document still can be a winner). Once the winner is determined, the conflict resolution is executed:
  • Create conflicts (no $ConflictAction item)
    The "loser" document is converted into a response document of the winner document and an item $Conflict is created. The conflicts are shown in in views unless excluded by view selection formula (& !@isAvailable($Conflict)). Conflict resolution is manual (an agent you write is considered manual too)
  • Merge conflicts ($ConflictAction = "1")
    If a document has been edited concurrently but different field have been altered, then they are merged into the one document and no conflict is created. If the same fields are altered a conflict is still generated.
    Sounds good? In practise I often see this fail, when true distributed edits by users are the conflict cause, since applications habitually contain a field "LastEditedBy" with @UserName as formula - a lesson to be learned when designing distributed apps: update only what is really necessary
  • Merge/No Conflicts ($ConflictAction = "3")
    Same as above: if different fields have been altered, then they are merged. If the same fields were altered the loser document is silently discarded. One could argue: why not merge at least the different fields. But that would create rather a data mess
  • No Conflicts ($ConflictAction = "2")
    The radical solution: the winner takes it all, the loser disappears and nobody will ever know. I haven't seen a good use case for that, but the world is big
So what to do about them? First you need to have clarity: They are called "Replication and Save" conflicts. So they can also happen on the same server. Some pointers how to prevent them:
  • Using document locking prevents them when edits happen on the same server
  • Also make sure, that you scheduled agent don't run on two servers concurrently
  • A nice rookie mistake is to use in a querySave (or postSave without closing the form) event - Domino will (or has) saved the document, get out of its way
  • Recheck your application flow: Can you limit the current allowed editor using Author fields/items? Quite often removing access in querySave combined with an agent altering access "on documents changed" makes a lot of sense
  • Check your forms: are there fields that are "computed" and changed by agents? You could/should set them to "computed when composed"
  • Avoid NotesDocument.computeWithForm(..) in agents unless you are sure it isn't the source of your conflict
  • If your business logic mandates that you have multiple concurrent edits, consider to implement the inversion of logging pattern (with XPages you can make that real snappy)
  • last not least: replicate more often or consider to cluster your servers
As usual YMMV


Gravatar Image1 - The Grammar Nazi in me is screaming; "It's 'loser' not 'looser'". The Notes Dev in me is yelling; "Yeah, I know that. So what?". The Blogger is me is shouting; "Nice Article".

Gravatar Image2 - @Dragon: for the grammar Nazi: wrong party, the spelling Nazi would have been needed Emoticon, but fixed now. For the Notes dev: "Always send the elevator back downLink" and for the blogger: glad you like it.

Gravatar Image3 - Thanks Stephan. The Grammar Nazi is back in his box. The Spelling Nazi has headed off elsewhere muttering about "your, you're, and yaw". The Notes Dev needs to take his finger off the lift call button and the Blogger is currently digging through the old blog articles trying to find the one which has a special form for handling conflicts by showing all the differences between the original and conflict and allows the user to select which fields to keep before eventually deleting the conflict.

Gravatar Image4 - I've seen a lot of applications where edit history fields e.g."Jon Smith last updated on 1 Jan 2013" have caused conflicts. If two users edit the same document on different replicas then there's going to be a conflict, even if they edited different fields and merge conflicts is turned on.

For Notes client applications it's worth noting the distinction between "soft locking" which is operating by default and "document locking" which you need to turn on. "Soft locking" prevents users on the same server from editing the same document. "Document locking" locks documents across all replicas on multiple servers.

Gravatar Image5 - thanks for explaining.

Are there any tools available that can help us with replication conflicts e.g. merge docs?

Gravatar Image6 - Profile documents have set automatically the radical solution with $ConflictAction="2".

If this selection makes sense for other "normal" documents I cannot say.

But the existance of this value makes sense, since you have no opportunity to "solve" a conflict in a profile document.


This site is in no way affiliated, endorsed, sanctioned, supported, nor enlightened by Lotus Software nor IBM Corporation. I may be an employee, but the opinions, theories, facts, etc. presented here are my own and are in now way given in any official capacity. In short, these are my words and this is my site, not IBM's - and don't even begin to think otherwise. (Disclaimer shamelessly plugged from Rocky Oliver)
© 2003 - 2015 Stephan H. Wissel - some rights reserved as listed here: Creative Commons License
Unless otherwise labeled by its originating author, the content found on this site is made available under the terms of an Attribution/NonCommercial/ShareAlike Creative Commons License, with the exception that no rights are granted -- since they are not mine to grant -- in any logo, graphic design, trademarks or trade names of any type. Code samples and code downloads on this site are, unless otherwise labeled, made available under an Apache 2.0 license. Other license models are available on written request and written confirmation.