.Domino Framework

Getting document locking to work has been one of my toughest assignment as a Notes developer.   But I have finally gotten a solution that passed QA.  So further to my previous FOUR blogs on this topic I can add the additional insight for others strugging to make document locking work (I know a few Notes developers that just gave up)

1. Don't allow provisional locks.  These are the locks that occur when the master lock server is down.  When this server is down it is like not having document locking at all.  Provisional locks can only be preveneted by coding EVERYTHING through LotusScript.
2. Persistent temporary locks only work to a degree.  These are the locks that occur when a document is placed in edit mode.  With every application I have implemented document locking I have found documents popping up (usually 1-2 a week) that remain locked even after  the document has bee closed.  Users of these applications can become confused (and frustrated) about these locks and in some cases are unable to remove the locks themselves.  If you can leave with this annoyance it is a LOT easier to implemen this model.
   
3. The only reliable way to get document locking (and unlocking) to work is to allow persistent permanent locks only.  These are the locks that are placed manually before the document is opened.

Implementing persistent permanent locking only is waaayyyy  more challenging.

1. The document locking event always occurs before any form event has a chance to respond.  So you cannot intercept (and prevent) a document locking action.  All you can do is detect and respond to a document locking operation.
2. Users with Manager level access to a database can overide an existing lock.  Unless care is taken these people can inadvertently destroy the integrity of the document locking process.
3. After a document has been opened in edit mode it is not possible to differentiate between a permanent persistent lock and a permanent temporary lock.

In implementing a solution to the above I have now completely rewritten the logic for the DominoDocumentCollection.Lock and DominoDocumentCollection.UnLock methods.  These methods now make use of a 2nd field that is added to documents when they are locked.  This 2nd field helps to identify that a persistent permanent lock has been placed and who placed it.  The form events must now be programmmed to check for the presence of a lock holder and 2nd field before allowing editing of a document.   Additionally we can inspect the current usname against the lockholder and 2nd field to identify a Manager who has been able to lock the document without originally holding the permanent persisent lock.  When this happens you can chose to refuse the edit request and restore the lock back to orginal lock holder.
To the application users the process looks like this.  They must first place a lock on one or more documents.  This is done from relevant views via a view action and/or using an inviewedit process to toggle a lock icon by clicking on the relevant column in the view.  An icon is added to the views to show documents that are locked.  Locks do not work if the Master Lock Server is not available.  Lock holders can then edit the locked document(s).  When they are finished they must unlock the document.  An Administrator with Manager level access can unlock documents locked by others (at their own peril!).
A working example of this will be included as part of the next release of the .DominoFramework.
Note: With Notes 6.0 it is not possible to edit attachments where a lock already exists.  (This is not the case with Notes 8.0).  To get around this issue I have devised a 2nd form that can be used to edit attachments.  This form does not contain the event trapping to prevent a document being edited when locked.  To reduce the risk of persistent temporary locks remaining, these are always removed when the document is closed (i.e lockholder is present but 2nd field is absent).

Document Locking continues to be a frustration for me to implement.  Despite all my best endeavours I have simply not been able to implement Persistent Temporary document locking with Notes 6.0 so that it works reliably.  I have in which it is important to ensure that (1) only one person can edit a document at any one time, (2) documents do not remain in a state where they remain locked by a person who is unable to remove the lock, and (3) no replication/save conflicts occur .  Unless soemone has a brilliant solution it seems the simplest way to achieve this is to supp[ort Persistant locks only in which the user must first lock the document manually, then edit the document, before releasing the lock.

 

In providing the above solution I have now extended the .DominoFramework and provide an example inside the framework of how to impliment persistant document locking.  This involves adding an icon to a view to display an icon next to documents that have been locked.  Clicking on the icon toggles the lock of/on using InViewEdit.  View actions are also provided to support the locking/unlocking of documents.  To prevent persistant temporary locks (the lock you get by default when you attempt to edit an unlocked document) I have wired the onQueryModeChange event to call a method that validates that a persistant lock already exists.  This code will all be abvailable as part of the next beta release of the .Domino Framework.

I have also added to the .Domino Framework Wiki with content about what I have learnt and suggest when working with Notes document locking:-

 

Document Locking allows Notes application to control edit access to a single document by more than one user. The standard Notes Document Locking feature will only work where an Administration Server (aka master lock server) has been nominated in the ACL of the database and the Allow Document Locking property set for the database.

Lock Types

The following are the different lock types that can occur on a document:-

Type	Description
Persistent	This occurs when the user (or code) places a lock on the document directly.
Persistent Temporary	This occurs when the user attempts to edit a document and the master lock server is available and permits the lock. The lock is supposed to be removed when the user finishes editing the document, but this is not always the case.
Provisional	This occurs when the user (or code) places a lock on the document directly and the master lock server is not available. The provisional lock may be promoted to a persistent lock when the master lock server becomes available.
Provisional Temporary	This occurs when the user attempts to edit a document and the master lock server is not available. The lock is supposed to be removed when the user finishes editing the document, but this may not always be the case.

Fields

The following is a list of fields used in supporting document locking:-

Field	Description
$PTWriters	Names of the people/groups holding a provisional temporary lock on a document
$PWriters	Names of the people/groups holding a provisional lock on a document
$Writers	Names of the people/group holding a lock on a document
$WritersDate?	Date/time document was locked

Errors

The following are some of the errors associated with document locking:-

Error	Description
4000	User is not authorized to lock/unlock the document. This can occur if the user does not have edit authority for the document or they are attempting to unlock a document locked by somebody else without manager access.
4595	Document has been locked by somebody else
4597	Master lock server not available

Best Practices

• The only reliable way to implement document locking seems to be to support persistent locking only (not persistant temporary locking). This requires that a lock be placed on a document when the master lock server is available. The document can then be safely edited before the lock then released.

• To prevent a persistent temporary lock being created it is necessary to prevent the document being placed in edit mode when first opened. This is best handled in the PostOpen? event by setting Source.EditMode? = False. It is also necessary to prevent a document being placed in edit mode unless the document already has a persistent lock. This is best handled as part of the QueryModeChange? event.

• If the form has an Edit action then hide the Edit action if the name in the $Writers field is not the current user.

Notes

• A person with Manager access can unlock/edit a document locked by somebody else. If you wish to prevent this happening from inside LotusScript code, check the contents of the $Writers field first before invoking the Unlock method.

• There seem to be a number of scenarios when can result in a temporary lock remaining after the user closes a document or switches from edit mode. These locks must be removed manually or via an agent (lock decay).

• When edit locking is implemented, it appears that if another person attempts to edit the same document on another server then the updated copy of the document is used even if replication has not yet taken place. I accnot find any documentation on this, but it seems to be a BONUS.

• If a document is opened in read mode and somebody subsequently edits the document, the original user will receive a warning if they then try to edit the document they have open. They are warned that they should close the document and re-open it (to get an updated copy). If they ignore this warning and try to edit the document a second time no warning is displayed and the old version of the document becomes editable. this will almost always result in a replication conflict and/or an e-mail being generated that warns about the potential loss of data.

• If locks are placed on a local replica of the database, details about the lock may not replicate to the other servers. In this case the master lock server is still aware of the lock even though the server documents do not contain the $Writers and $WritersDate? fields.

Related Information

• A Guide to Document Locking in Notes/Domino 6

A "Dirty Read" occurs when a document you open a document in read mode and somebody subsequently edits the document.  You now have a copy of the document which is no longer valid.  If document locking is enabled for an application then Notes detects this situation and prompts the user to close the document and reopen it from the view.  The document remains in read mode.  In Notes 6.0 at least, if you again attempt to edit the document it actually allows you to edit the document without having re-opened it.

 

A a way of preventing dirty reads the .Domino Framework has added a PreventEditIfLocked method to the DominoDocument class (See previous blog).  This method now supports two ways of handling the situation.  The first is to close and reopen the document.  But this does not seem to always refresh the document.  The second (new) option is to display the same Notes error message and remain in read mode via a new DirtyReadAlert method.  This exposed what appears to be a "bug" in Lotus Notes (NO.... I hear you say!!).  It would seem that the document locking mechanism does not handle the situation in which a QueryModeChange event returns false and the document does not switch to edit mode.  The edit lock is already in place and because the document is now not in edit mode is does not unlock the document when it is closed leaving the document permanently locked.  To address this scenario the DIrtyReadAlert also unlocks the document.

 

'/**
 ' *  If document is locked by another person then prevent document from being edited.  Used with document lcoking, this prevents potential conflicts that can occur
 ' * if a document is placed in edit mode after another has changed the document on another server.  Action taken can be either to repeat the same message generated
 ' * the first time by Notes, or to close and re-open the document
 ' *
 ' * @param Source     The NotesUIDocument to be protected
 ' * @param DisplayMessage True = Display message each time, False = close and re-open document
 ' */
 Sub PreventEditIfLocked(Source As NotesUIDocument,DisplayMessage As Boolean)
  If Me.IsLockedBySomeoneElse Then
   If DisplayMessage Then
    On Event QueryModeChange From Source Call DirtyReadAlert
   Else
    On Event QueryModeChange From Source Call ReloadDocumentFromView
   End If
  End If
 End Sub
 Private Sub DirtyReadAlert(Source As NotesUIDocument,Continue As Variant)
  On Error Resume Next
  Call Source.Document.UnLock
  Msgbox "Document has been modified since opening, reopen in edit mode from view.",,"Lotus Notes"
  Continue = False
 End Sub

With Notes 6.0 there appears to be a bug with document locking in the scenario in which UserA is editing a document and UserB then attempts to edit the same document on another server while UserA is still editing the document. When this happens UserB will be able to open the document but it will remain in read mode while UserA is editing the document.  When UserA has finished editing the document UserB can then place the document in edit mode.  The first time this is attempted a warning message is issued that USerB must re-open the document from the parent view and the document remains in Read mode.  If UserB ignores the message and again attempts to edit the document without reopening it from the parent view the document actually opens in edit mode.  If UserB then closes the document without making any changes, a lock is placed on the document by UserB that is not released after the document is closed.  This can lead to an accumulation of locked documents in the database.

 

To solve this scenario I have extended the .DominoFramework as follows:-

 

A property has been added to the DominoDocument class that allows the detection of a document that is locked by somebody else:-

 

Property Get IsLockedBySomeoneElse As Boolean
  IsLockedBySomeoneElse = iDocument.LockHolders(0) <> "" And Isnull(Arraygetindex(iDocument.Lockholders,Session.UserName))
End Property

 

A new PreventEditIfLocked method can then be invoked by the PostOpen event on the form.  This adds additional code to the QueryModeChange event to trap the scenario in which a locked document is subsequently placed in edit mode:-

 

 Sub PreventEditIfLocked(Source As NotesUIDocument)
  If Me.IsLockedBySomeoneElse Then On Event QueryModeChange From Source Call Reload
 End Sub

 

The Reload method that is now triggered by the OnQueryModeChange event then closes the document and re-opens the document.  This is done via an agent as I was unable to find any other way of forcing the current document to be closed and the re-opened.  It was also necessary to unlock the document at this stage as it appears this is where the forgotten lock is enabled.

 

Sub Reload(Source As NotesUIDocument, Continue As Variant)
  Dim Agent As NotesAgent
  
  On Error Resume Next
  Call Source.Document.UnLock
  Call Source.Close(True)
  Set Agent = DB.GetAgent("aReopenDocument&quot
  If Not Agent Is Nothing Then Call Agent.Run(iDocument.NoteID$)
 End Sub

 

And finally, the agent to open the document is as follows:-

 

Sub Initialize
 Dim Session As New NotesSession
 Dim UIW   As NotesUIWorkspace
 Dim Agent  As NotesAgent
 Dim Doc   As NotesDocument
 
 If Session.IsOnServer Then Exit Sub
 Set Agent = Session.CurrentAgent
 Set Doc = Session.CurrentDatabase.GetDocumentByID(Agent.ParameterDocID$)
 If Doc Is Nothing Then Exit Sub
 Set UIW = New NotesUIworkspace
 Call UIW.EditDocument(True,Doc,,,False)
 
End Sub

 

All of the above code will be included as part of the 0.4 beta of the .Domino Framework planned for this weekend.

 One of the projects I am presently working on involves enabling document locking for an application using the Document Locking feature introduced with Notes 6.0.  I had done this before with Notes 6.0 and recall there are issues with documents sometimes remaining locked even after the user has finished editing the document.  And sure enough, when we started UAT we got reports of document being locked even though no-one was still editing the document.  As part of the process for resolving this I have added Document Locking as a new feature within the .Domino Framework.

 

A new view ($Locked) has been created as a way of clearly displaying those documents that are presenty locked (i.e. the $Writers fields is present).

I have added a view action to remove the lock by deleteing the $Writers and $WritersDate field from the document .  This allows people without Manager access to maintain the locks.

 

Testing done so far has shown that when the lock fails to be removed,  the $writers field is present but the $WritersDate field is not present.  I have therefore added a RemoveInvalidLocks method to the DominoDatabase class that will remove any document in the ($Locked) view for which this situation arises.  By creating an agent the runs periodically against the database invoking this method it is possible to locate and correct these issues as they occur.

 

Note: Further testing is still required to ensure that only invalid locks are being removed and that this technique is identifying all the document locks that persist after they are no longer needed....