« Places I've Been | Main| Presenting SuperNTF (and more) at the VIEW Lotus Developer2008 Conference »

Coming to SuperNTF - Document Locking That Rocks


External ImageHello Everyone, remember me? Great, thanks for your patience. I will now begin to reward it.

You'll be happy to know that I've been busy cooking up batches and batches of cool stuff, ranging from (hopefully) entertaining and informative session slides to slick (and useful!) new SuperNTF features. The long rainy weekend passed with little human contact ("Yes Honey, I promise to eat vegetables while you and Junior spend 2 months visiting your family."), and the basic rhythm went something like this:

Sub Initialize

Forall days in Weekend
       feed cats
       eat(True)   'optional parameter indicates whether coding occurring simultaneously
       HDTVbreak("Discovery Channel", True)   'True indicates, you guessed it, coding
       feed cats
       HDTVbreak("Saturday Night Live", True)
       sleep(True)        'optional parameter indicates whether dreaming in code
End Forall

End Sub

As the title of this post suggests, the primary focus of this intensely focused coding binge was document locking.  As you are all no doubt aware, document locking has been a native feature of Notes since version 6. Unfortunately, utilizing this cool new functionality, which previously required all kinds of coding heroics to achieve, isn't as simple as turning it on and living happily ever after.

Once you get past the basics, there are a number of implementation best practices necessary to override some default behavior that can result in bad things happening (e.g. data loss).  Without getting into too much detail, one of the techniques I've adopted is to explicitly lock a document (with a "persistent lock") before it is placed in edit mode, which allows me to prevent Notes from issuing a "provisional" lock if the master lock server (i.e. the Admin server) is unavailable.  Provisional locks occur in cases when documents in offline local replicas (or any "disconnected" replica for that matter) are edited. They are bad because those changes might be lost completely if another person edits the same document in between replications. The worst that can happen when using this technique is that a replication/save conflict is created, which can always be manually reconciled (I highly recommend Ytria ScanEZ for conflict resolution).

Another key problem with document locking that isn't addressed adequately is "forgotten" locked documents. This can happen when a user manually locks a document and neglects to unlock it later, or their Notes client crashes while editing a document.  I've approached this problem in two ways. The first is to create a view showing all locked documents and by whom and when they were locked. This view contains an action allowing administrators to manually remove the locks.

A picture named M2

The second approach is to implement a scheduled agent that checks for locked documents that have been "abandoned" for longer than some configurable amount of time, and then removes the locks and notifies the lock holder it has done so.

For user convenience I've also added elements to forms that display a document's current lock status, and all views contain an icon column that shows a lock next to any locked documents.

A picture named M3

A picture named M4

To build all this I was helped tremendously by a great VIEW article and accompanying database by James Ray, as well as a great bit of code written by Chad Schelfhout. Definitely worth checking out both, although the best bits from both these sources have been distilled for ease of use in the upcoming SuperNTF release, so you may want to hold off playing for another couple weeks (I hope ).

Stay tuned for more...


1 - @Kevin,
Hope all is well!
I'm having issues with a 6.5 version of doc locking. I opened a support ticket with Lotus Support. They provided a fix that we applied to our test server and we will be applying to prod soon. We have an application that has a couple docs a day that won't willingly give up the lock. Difficult to troubleshoot as I don't know what the user could possibly be doing that would cause this. I don't think they're savvy enough to be locking these docs manually and forgetting. I like your thoughts/code on running an agent to unlock especially if this fix does not do the trick. Can you share this code? Thanks!

2 - Hey Curt! The "lock decay" agent I'm working on is adapted from that in the sample DB in the VIEW article referenced above. I've changed a few things related to how it logs activity and what lookup views it uses, but otherwise haven't done much with the core code. It's possible I will make such changes, but that will depend on how some of my other troubleshooting goes.

The problem I'm trying to handle now was reported by another SuperNTF user, and relates to what is essentially a Notes bug when using document locking in combination with soft deletions: { Link }

I can reproduce this problem pretty easily but I still haven't perfected a fix that will allow for the soft deleted documents to be restored AND unlocked at the same time. I can certainly lock before deleting, but after that things are still messy. If anyone has thoughts on how to LOCK - SOFT DELETE - UNLOCK so that documents in the Trash are unlocked, please share.

As mentioned above, I'm currently working on the approach of leaving the documents locked in the trash, and unlocking them during the restore process. I've had some success with this but so far the documents seem to come back slightly corrupted, thinking they are still deleted but showing up normally. Emoticon

3 - UPDATE: I think I've cracked the "must lock before delete" issue. It seems a "brute force" approach to lock removal will work. By "brute force", I mean that instead of using the built in locking functions of Lotusscript or @Formula, I directly remove the specific document fields (items) that control locking. For those that don't already know, when a document is locked two fields are added to it: $Writers and $WritersDate. These store the "who locked me?" and "when did they lock me?" information. The only downside to the brute force approach is that, unlike the locking functions, the document's modified time will be affected. But since we're restoring the document, that's already happening anyway. Translation: no downside.

I still have some cleanup in terms of exception handling, as well as more testing to confirm that users with lower access levels but the right roles will have the desired capabilities. I may even try to remove the locks via brute force at deletion time instead of on restore. We'll see.

4 - The document locking caught my eye so I had to stop by to see if could help. And to my disappointment I could not, because I already had. Glad to see the class being used Emoticon

5 - Hey Chad,

Actually you can help. While I've used your class for the basics of locking and unlocking, I'm not sure I'm doing using it to its full potential. I also think there are probably other uses that I'm overlooking. What's missing from your download are usage examples for each of the various class features. Can you post an example db to show how the pieces all fit together?

Thanks Emoticon

6 - Hi Kevin:

I has the problem on soft locking.
Domino Server: R6.5.4
Platform: Windows 2003

The database disable "Document Locking".

User A edited, saved and closed the document.

At the same day, other User B edited the same the document, the message "The document is locked by User A" prompts.

Why the document is locked by user A even he exit the application?

7 - Hi Kevin,

Im just a newbie with lotus notes 6.5 and I was thinking I could ask for your help in document locking . . .we have an application where when user A opens a document and clicks on the "Edit" button (the code in the button is simply @Command([EditDocument])) and then user B opens the same document and clicks on the "Edit" button, user B gets the message "The document is already locked by user A . . .".

This is good because User B is not able to edit the document but the problem is the document never closes on User B's screen. It just remains open and then when later on when User A decides to close the document on his end, the lock is released and so User B is able to edit and save the document which results in a replication or save conflict and the data saved by one of the users get lost.

Would it be possible for us to change the setting of the lotus notes system so that after User B gets the message "The document is already locked by user A . . ." the document will automatically close on user B's screen so he wouldn't have the chance to leave the document open and then cause a replication/save conflict error message later on?

Ive tried putting in code in either the "Querymodechange" or "postmodechange" event that will trigger the closing of the document after the message "The document is already locked by user A . . ." appears but I cant seem to get it to work right.

Any information would be greatly appreciated Lotus Guru =)

Thanks so much in advance! =)

8 - Hi Kevin,

I'm new to document locking. I have an app that seems to generate emails with the subject "Changes made to database - database name- have NOT been incorporated into the database. There was a conflict detected. Your changes may be found in body of this message. A document link to the original document is attached to the e. . ." This email seems to be generated every time a user accesses a doc, even if no one else is in it. Is there a way to disable the notification?

29 - How does one get the sample Databse for hte Locking code, etc...?

Post A Comment


Your Host

Kevin Pettitt View Kevin Pettitt's profile on LinkedIn

Tools I Use

Idea Jam

Subscribe to This Blog

 Full Posts  Comments

netvibes Add to Netvibes


Hosted by



This site is in no way affiliated, endorsed, sanctioned, supported, nor blessed by Lotus Software nor IBM Corporation, nor any of my past or future clients (although they are welcome to do so). The opinions, theories, facts, etc. presented here are my own and in no way represent any official pronouncement by me on behalf of any other entity.

© 2005-2019 Kevin Pettitt - all rights reserved as listed below.

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