A Guide To Document Locking in Notes/Domino 6

A Guide to Document Locking in Notes/Domino 6
A Guide to Document
Locking in Notes/Domino 6
James Ray
The new document locking functionality in Notes/Domino 6 has been

long wished-for, sorely needed, and enthusiastically welcomed by
administrators and developers alike.
James Ray specializes in

enterprise integration with
Oracle and SAP, Web development, and Notes/Domino 6
migrations. He is a Principal
Certified Lotus Professional
(IBM Certified Advanced)
System Administrator and
Application Developer for
Notes and Domino releases 4,
5, and 6, as well as a Microsoft
Certified Systems Engineer.
You can contact him at
jimmyraywv@yahoo.com.
Most software users are familiar with the concept of document or

record locks. In a relational database, records can be locked to prevent
editing of records by multiple users at the same time. In word-processing
software, document locking prevents users from editing documents
that are being edited by other users. In collaborative applications, where
many users have Editor access to the same documents, the ability to
lock documents is especially desirable. Until Notes/Domino 6, however,
native document locking was not available, and developers and
administrators had to look to third-party add-on products or homegrown
solutions for document locking functionality.
Lotus Notes/Domino 6 document locking provides robust functions
that can make applications more sturdy and user-friendly. It is not,
however, the panacea for save and replication conflicts that many had
hoped it would be. There are new issues and requirements relating
to application implementation, architecture, and business practices,
all of which need to be addressed before you can deploy document
locking successfully.
To help you get the most from this new feature and make
informed decisions for successful implementation, Ive written this
article to serve as your essential guide to Notes/Domino document
locking. It covers the out-of-the-box functionality, a look at whats
happening under the covers, things to watch out for, and how, when,
and why to customize.
(complete bio appears on page 32)

No portion of this publication may be reproduced without written consent.
THE VIEW September/October 2004
Ive created a demonstration Notes/Domino 6.5

database (doclockd.nsf)1 that includes sample code for
the examples in this article, including:
Native Notes/Domino
Document Locking
9 LotusScript code to apply and remove locks using

document locking methods
In Notes/Domino 6, document locking is the process

you can employ to prevent users from editing certain
documents when those documents are being edited by
another user. The lock holder of a document can be
a single user or a group of users. When a Notes client
user attempts to edit a document that is already locked
by another user, the user is notified immediately
via a modal, pop-up dialog box that the document
is locked by another user and cannot be edited while
it is locked. (Well look at Web client operation
later.) By locking the document, Domino prevents
the race condition2 that occurs when different users
edit the same document almost simultaneously.
Domino forces the editing process to be serial and not
parallel, thereby reducing the chances of conflicts.
(For a summary of what happens when multiple users
edit a document at the same time without document
locking enabled, see the Replication and Save
Conflicts sidebar.)
9 Formula code to remove lock items from a

document
9 A solution for locking and unlocking documents
via in-view editing, including code to change
view column custom colors to indicate lock status
and the type of lock applied
9 A lock decay solution to avoid permanently
locked documents that have been forgotten by
the users who locked them
9 A check-in/checkout solution for effective
document locking on the Web
Well start with a look at the native Domino
functionality.
At www.eVIEW.com, click THE VIEW Journal > Download Files >

September/October 2004 > the title of this article. Scroll to the bottom
of the abstract page for the download link.
A race condition (or hazard) is deviant behavior that occurs in a process

due to a critical dependence on the sequence of events.
Bonus Information
As a bonus, the Document Locking Demo database
(doclockd.nsf at www.eVIEW.com) includes these
useful libraries not mentioned in the article:
GetQueryStringArgument Parses the
query string argument from the query_string
CGI variable.
libAgentLoggingClassV2 A LotusScript
library that contains a user-defined class to perform logging of agent execution. Used in the
LockDecay agent.
libDocLocking LotusScript library where the
bulk of document locking code is kept.
libMisc LotusScript library that houses

miscellaneous functions such as getting keywords and database objects.
libReplaceSubstring Has two versions
of a LotusScript function to replace a substring
a plain one and a version that uses the
Evaluate() function to execute formula language
inside the LotusScript code.
libSecurityClass Used in
libAgentLoggingClassV2 and libDocLocking.
libStringFunctions Miscellaneous string
functions.
www.eVIEW.com
2004 THE VIEW. All rights reserved.
How Documents Are Locked
Whats Happening Behind the Scenes?
In order for a user or agent to lock or unlock a document,

the user (or executor of an agent) must have at least
Author-level access to the database, and he or she
must also have Author access to the document. If the
document is locked and the user is trying to unlock it,
the user must also be the explicit lock holder for that
document or in the group that is listed as the lock
holder. If these requirements are met, there are five
main ways to lock/unlock a document:
There are a whole host of clever activities taking

place behind the scenes when a document is being
locked or unlocked. Before I show you whats going
on, however, Ill explain the types of locks that Domino
provides and the system topology that supports document
locking, so you can better understand how Domino
supports document locking.
Select the document from a view or folder and

choose Lock/Unlock Document from the
Actions menu.
Document Locking Topology

and Lock Types
Select the document from a view or folder

and choose Lock/Unlock Document from
a pop-up menu.
Automatically lock and unlock the document by

editing the document.
Programmatically lock and unlock the document

through the use of Notes formula language or
LotusScript code (in Notes/Domino 6.0) or Java
code (in Notes/Domino 6.5).
The first requirement of document locking is that any

database that uses document locking must have a master
lock server defined in the database ACL, and the
database must be able to reach and communicate with
the master lock server. This requirement applies to databases on Domino servers as well as databases on local
Notes clients. As you might expect, you will need to pay
attention to this requirement when setting up multiple
replicas of databases, especially replicas on remote
user desktops or remote servers with limited replication.
Programmatically lock and unlock the document

through direct editing of items on the document
backend.
Once a document is locked, it cannot be edited

by anyone except the lock holder or holders. Even a
user with Manager access to the database cannot edit
the document if he or she is not a lock holder. Users
with Manager access can, however, unlock the document
and then edit it. In fact, the manager of a database
can unlock any document, regardless of whether or
not he or she is the lock holder.
The second requirement is that the master lock

server must contain a replica of the database that has
document locking enabled. Locks are applied and
removed in the replica on the master lock server, and
lock statuses are propagated to replicas on other
machines. (Well go into how this is done later.)
When a user requests to lock or unlock a document
in a database in which document locking is enabled,
Domino first determines whether or not the database
in which the request is being made is the same database that is on the master lock server:
If the database in which the request is being made

is on the master lock server, then Domino next
determines whether the user is allowed to lock
or unlock the target document, given the users
database ACL level and the lock holder status of
the document.
If the master lock server is remote to the database

in which the request is made, then Notes remote
procedure calls (NRPCs) are made to the master
Note!
Users with Manager access must be careful when
exercising their authority to unlock a database
document. If they edit the document, they could
cause a conflict condition.
lock server to find out whether the document is

available for locking/unlocking. These calls take
place immediately if there is a current connection
to the master lock server; if there is no current
connection, they take place at the next replication
or the next time a connection is made.
Depending on the topology of the database replicas
and how a document is locked, a user can expect to
see one of four different types of locks applied to a

document: persistent, persistent-temporary, provisional,
or provisional-temporary. To illustrate these lock
types, Ill take you through some example scenarios.
In each scenario, the target database is the one in
which a user is attempting to edit a document.
Scenario 1 (demonstrates persistent locks)

The target database is either on the master lock
Replication and Save Conflicts

In Lotus Notes, the Notes Object Service (NOS) keeps
track of when a document is edited and how many
times the document has been edited. It does this by
monitoring and changing values in the documents
$Revisions item and originator ID (OID) whenever the
document is edited and saved or revised. The OID
of a document contains the documents universal ID
(UNID), a sequence number, and a time stamp. The
UNID is a 32-digit, hexadecimal number that is unique
to each document across all replicas of a database.
In fact, according to the Inside Notes database on
the Lotus Domino Developer site, Except for notes
in replica copies of a database, no two notes in any
databases anywhere in the world should ever have
the same UNID. +
The OID sequence number indicates how many times
a document has been edited, and the time stamp
indicates when the document was last updated.
The $Revisions item contains a list of time stamps for
when the document was revised (the last entry in
the $Revisions field is actually the OID time stamp).
Together, $Revisions and the OID make up the reference indicator to the instance of the Notes document.
Conflicts can occur when different users are editing
a document at the same time. In this situation, there
is a race to determine which user will have his or her
changes saved in the document and which user will
not. There are two types of conflicts: save conflicts
and replication conflicts.
+
http://www-10.lotus.com/ldd/notesua.nsf/find/inside-notes
A save conflict occurs when users are editing the

same document (or, more precisely, the same
instance of a document in the same database replica
on the same server) at the same time. A save conflict
results in a Lotus Notes response document that is
linked to its parent document. In this situation, the
parent document contains the edited data from the
conflict winner, and the response document contains
the edited data from the losing editor.
A replication conflict occurs when different users edit
different instances of the same document in different
replicas. Like save conflicts, replication conflicts
produce a winner with changes saved in the main
document and a loser with changes saved in a
response document.
Notes determines the winner and losers of a conflict
using a documents $Revisions and OID information.
If a conflict is created (i.e., $Revisions has the same
number of entries in each document instance, but
the last entries in the two documents do not match),
the winner will be the document with the lowest
sequence number in its OID. If the sequences are
the same in the OIDs, the winner will be the document
with the most recent time stamp in its OID.
There are some replication and form design settings
that have the potential to reduce the chances of
these conflicts; however, Notes/Domino 6 document
locking, if employed successfully, can prevent conflicts
by stopping users from editing documents that are
already locked.
www.eVIEW.com
server or on a machine (server or client) that can

readily communicate with the master lock server.
A user manually or programmatically requests to
lock or unlock a document in the database.
Scenario 2 (demonstrates persistent-temporary

locks) This scenario uses the same database
configuration as scenario 1; the difference is that
the user is attempting to edit a document without
manually requesting that the document be locked
first (i.e., the user simply attempts to edit the
document via the user interface).
Scenario 3 (demonstrates provisional locks)

The target database is not on the master lock
server, and the master lock server is unavailable.
The user manually requests to lock or unlock a
document.
Scenario 4 (demonstrates provisional-temporary

locks) As in scenario 3, there is no communication with the master lock server, except now the
user is locking the document as part of opening it
in edit mode (without first manually locking the
document).
Scenario 5 (demonstrates the types of locks
possible in situations where programmatic
locking is attempted and the master lock server
is unavailable) The possible outcomes in this
scenario are the application of provisional locks
or documents that cannot be locked at all.
As these scenarios will make clear, the persistent

lock is the only type of lock that is safe that is, a
persistent lock ensures the prevention of data loss or
conflicts, while a provisional lock does not.
Scenario 1 Demonstrating Persistent Locks

In scenario 1, the target database is located on either
the master lock server or a machine (server or client)
that can communicate with the master lock server via
a persistent network connection or dial-up.
When a user requests to lock or unlock a
document in the target database, Domino checks
the instance of this document in the replica on the
master lock server:
If the document is already locked, the lock

operation will not be permitted.
If the lock operation is allowed and the user is

allowed to lock/unlock the document, then
Domino applies a persistent lock to the document
instance in the replica on the master lock server
(and on the instance in the target database as well,
if it is not on the master lock server). The user
can then choose to edit the document or not, as
the document is now locked from other users and
will remain so until another process unlocks the
document (e.g., a manual unlock from the UI or a
programmatic unlock).
If the request is for an unlock operation and it is

allowed by the master lock server based on the
users ACL level, then the target document is
unlocked.
Persistent locks are safe in the sense that they can

ensure only one user can hold a lock on a document
at any given time. Thus, users can edit documents
without fear that data will be lost. As youll see,
persistent locks are the only safe locks to use.
Scenario 2 Demonstrating
Persistent-Temporary Locks
Scenario 2 is very similar to scenario 1 in that the
target database is either on or can communicate
readily with the master lock server. In this case,
the user is attempting to edit a document without
manually requesting to lock the document first.
As soon as the user attempts to open the document
in edit mode through the UI, Domino communicates
with the master lock server and determines
whether the user is allowed to lock the document.
If the user is allowed to lock the document and if
the document is available for locking, the master
lock server places a persistent lock on the document.
However, this persistent lock is only temporary;
it will be removed after the user closes the
document in the UI.
A persistent-temporary lock is considered safe, as
it ensures no one else has the document locked while
it is locked for this user. It differs from a persistent

lock in that it is unlocked immediately upon ending
the editing session instead of persisting until another
process unlocks the document.
Tip!
It is a good idea to design UIs (forms and views)
so that end users know the status of a document.
A simple computed text label on the form suffices
to indicate the current lock status of the document being edited.
Provisional Locks
Clicking the Yes button in the dialog shown in

Figure 1 causes a provisional lock to be placed on
the document. If the user clicks No instead, then a
second dialog pops up (see Figure 2) to inform the
user that the master lock server was unavailable. In
this case, no lock is applied to the document.
Best Practices
In scenario 3, the user manually requests to lock or

unlock a document in a database replica that is not
on the master lock server, and the master lock server
is unavailable. This is similar to the situation
encountered by users of local database replicas that
do not have a current network connection to the
master lock server. In this case, the user is notified
via a modal dialog box that the master lock server
is unavailable (see Figure 1; the truncation in the
dialogs text is reproduced as it naturally occurs).
The user is asked if he or she would like to use a
provisional lock to lock the document.
Figure 1
The idea behind a provisional lock is that it can

be promoted to a persistent lock later, when the master
lock server becomes available. The catch is that the
lock can only be promoted to a persistent lock if the
document was not already locked through the master
lock server at the time that the persistent lock was
requested and the provisional lock was applied. Later,
well look at what happens when there is an attempt to
promote a provisional lock. For now, suffice it to say
that if the promotion fails, the users edits will be lost.
Teach your users to accept only persistent locks.

Users should know that editing a document while
it is provisionally locked is risky the only way
to ensure their edits will be preserved and not lost
is to use a persistent lock.
You can optimize document locking in your environment by minimizing the situations that lead to
provisional locks that is, by ensuring that the
databases that have document locking enabled are
on machines that can readily connect or have a
persistent connection to the master lock server.
Create a Provisional Lock?
www.eVIEW.com
If the user is attempting to unlock a document that

is already persistently locked in the target database,
and the master server is unavailable, then the unlock
operation will fail, and the user will see a pop-up
dialog indicating that the replica of this database on
the master server is unavailable (see Figure 3). The
same error occurs when the master lock server is
available but the replica of the database is not on the
master lock server. In any event, the user should
understand that this message means that the document
is not safely locked theres no guarantee that his or
her edits will be preserved.
If a user is attempting to unlock a provisional

lock or a provisional-temporary lock (discussed
next) and the master server is unavailable, the
unlock operation will be allowed by the local
replica of the database provided that the user is a
member of the Lock Holders property of the locked
document, or the user has Manager access to the
database. However, the end user is performing this
operation without a safety net, and the operation is
not entirely reliable.
Figure 2
Scenario 4 is similar to scenario 3 in that there is no

communication with the master lock server. However,
now the user is requesting to lock the document as
part of opening it in edit mode. When the user tries
to edit the document, the document-locking mechanism
attempts to lock the document by communicating
with the master lock server. Since the server is
unreachable, the user is immediately prompted that
the master lock server and master replica are not
available, as shown in Figure 4.
The Message When the User Clicks

No on the Create a Provisional
Lock? Dialog
Provisional-Temporary Locks
Figure 3
The Master Lock Server Is Unavailable (Cannot Unlock Document)
Figure 4
The Master Lock Server and Replica Are Not Available
At this point, the user can either cancel the editing

attempt or click OK to continue and edit the document.
If the user chooses to continue, a provisional-temporary
lock is placed on the document. When this happens,
the user may also see a warning from Lotus Notes
that the document has been modified since opening
and it should be closed and reopened (see Figure 5).
Apparently, a race condition occurs when a provisional
lock is applied while a user has a document open and
is editing it. As youll see, Domino modifies the
document backend when a document is locked, which
may be why this condition occurs. In other words,
the process that modifies the backend of the document
to temporarily and provisionally lock the document
seems to conflict with the document being opened in
the UI.
finally communicates with the master lock server, the

provisional-temporary lock will then disappear.
Scenario 5 Attempting Locks with Programs

Scenario 5 is similar to scenarios 3 and 4 in that the
master lock server is unavailable, but scenario 5 also
covers the situation where the user is executing code
(either formula language, LotusScript, or Java) that is
attempting to lock a document. When the user executes
code in the Lotus Notes client to lock a document,
one of two things can occur, depending on how the
code is written and what language is used:
If the code is written in LotusScript or Java,

the developer can allow or disallow provisional
locks when the user cannot persistently lock a
document. This is accomplished by simply passing
a Boolean argument to the respective lock function
or method. If a true argument is passed, the
provisional lock will automatically be applied
if the persistent lock is not allowed; conversely,
if a false argument is passed to the function or
method, the lock will be denied and the user will
be prompted that the document cannot be locked
because the code cannot connect to the master
lock server (see Figure 6). To ensure that risky
provisional locks are not used in your applications,
I recommend that you pass a false argument here.
If formula code is being executed, there are no

arguments for allowing or disallowing provisional
locks when persistent locks are not possible. In
fact, there is no indication to the user that the
locking operation or, for that matter, the unlocking
The provisional-temporary lock is simply the

temporary version of the provisional lock and, as
such, it makes editing a risky proposition.
In addition, like its distant cousin the persistenttemporary lock, the provisional-temporary lock does not
require the end user to overtly unlock the document.
The provisional-temporary lock will disappear once
the user closes the document in the user interface and
the master lock server is available to clear the lock.
Therein lies the rub. The reason this lock was applied
was because the master lock server was unavailable.
This means that unlike the persistent-temporary lock,
the provisional-temporary lock may not immediately
clear when the locked document is closed in the UI.
Until the master lock server is available, the provisionaltemporary lock may linger. When the database replica
Figure 5
10
UI Editing While Document Is

Locked Causes a Race Condition
Figure 6
Cannot Connect to the Master

Lock Server
www.eVIEW.com
operation failed. There is simply no change to

the document.
Figure 7 summarizes the scenarios that we have
just discussed.
Lock Promotion
As youve seen, the persistent lock is the only type
of lock that is safe for allowing users to begin editing
documents. Provisional and provisional-temporary
locks are not intrinsically safe for allowing users to
make edits, because these lock types allow race
conditions to occur and could result in data loss.
The whole idea behind provisional and provisionaltemporary locks is that, when the master lock server
becomes available, they may or may not be promoted
to persistent locks.
If a user creates a provisional or provisionaltemporary lock on a document, the database replica
must communicate with the master lock server and
Figure 7
its replica to trigger an attempted promotion for the

locks. The user triggers this communication in one
of two ways by manually initiating replication
with the master lock server or by editing the document
while the master lock server is available. Both of
these actions trigger document locking NRPCs to
the master lock server, and the master lock server
attempts to promote any outstanding provisional or
provisional-temporary locks. (In the case of NRPCs
triggered by editing the document in the UI, the
attempt is to promote only the document being edited,
not all documents in the database.)
If the promotion is successful and the persistent
lock is applied, the user will receive a message in his
or her inbox that indicates a successful promotion and
that contains a doc link to the locked document. If
the lock promotion was unsuccessful, the user receives
a message that the lock was not promoted, and the
message will contain a doc link to the document that
is now locked by someone else. Figure 8 shows you
Dominos standard subject line for an e-mail message
that tells the user about an unsuccessful promotion.
Lock Types
Scenario
Lock Type
Master Lock Server Method to Lock Document
Safe for Editing
Persistent
Available
Manual/Menu
Yes
Persistent-Temporary
Available
Automatic with document editing Yes
Provisional
Unavailable
Manual/Menu
Provisional-Temporary
Unavailable
Automatic with document editing No
5a
Provisional
Note: An argument
may be passed to
allow/disallow locks
Unavailable
Programmatic LotusScript
or Java code
No
5b
None
Unavailable
Programmatic formula code
No
Figure 8
No
Subject of E-mail Message Indicating the Unsuccessful Promotion of a Provisional Lock
A provisional lock in database <YourDatabaseHere> has NOT been promoted to a hard lock. There was a
conflict detected. Your changes may be found in the body of this message. A document link to the original
document is attached to the end of the message.
11
If the user creates a provisional-temporary lock

by editing the document and saves the document under
that type of non-persistent lock, the user is now at the
mercy of the master lock server. If the document was
already locked by another user prior to the second users
edit/lock attempt, the provisional-temporary lock will
not be promoted. The unsuccessful user will receive
a message similar to the one for the unsuccessful
promotion of a provisional lock. Figure 9 shows you
Dominos standard subject for an e-mail message that
tells the user about a provisional-temporary lock failure.
Both failure messages tell the user that their edits
may be found at the bottom of the e-mail message.
In reality, that is not the case at least not in my
testing. Every time this situation occurs, the edits are
lost with no means of retrieval by even the savviest of
administrators. This shortcoming underlines the
precarious nature of non-persistent lock types and
strengthens the case for persistent locks as being the
only safe locks to allow user editing. In fact, losing
the data in an unsuccessful lock promotion is worse
than dealing with replication or save conflicts. At
least the data in a conflict document is retrievable
through manual means. Later, see the section
Document Locking Setup and Administration for a
discussion of how to prevent or minimize provisional
locks in your environment.
Behind the Scenes

Lets look now at whats happening behind the scenes
when a document is being locked or unlocked and the
master lock server is available for communication.
Communication between the master lock server and
the Lotus Notes client is in the form of NRPCs. It takes
approximately 16 NRPCs to lock a single document.
Figure 9
When a lock is placed on or removed from a

document, Domino is actually modifying the backend
of the document by adding or removing NotesItems.
These items indicate the type of lock and the user under
whose authority the document is locked or unlocked.
When a persistent lock or persistent-temporary
lock is applied to the document, two items are written
to the document, $Writers and $WritersDate. The
$Writers item contains the user or group (lock holder)
that has the document locked, and the $WritersDate
item contains the date that the document was persistently
locked. When the document is unlocked using the
document locking mechanisms, Domino removes
these two items from the document. In the case of
the persistent-temporary lock, the removal of the
items takes place immediately when the document is
closed in the user interface.
When a provisional lock is applied to a document,
a $PWriters item is added to the backend document,
and it too contains the explicit lock holder or group of
lock holders. Likewise, a $PTWriters item is added
for a provisional-temporary lock type. (As a point of
reference, the $Writers, $PWriters, and $PTWriters
items are author access items, functioning similarly to
Authors fields.) However, there are no $PWritersDate
or $PTWritersDate items added to the document, even
though some Lotus Domino documentation seems to
suggest that there should be. In my testing with
Notes/Domino 6.5, I never saw these items applied to
locked documents. Apparently, Lotus intended the
$PWritersDate and the subsequent $PTWritersDate
items to be used for a lock decay feature that never
made it into release 6. We will discuss lock decay
later in this article.
Adding items to a documents backend without
editing them through the UI is not such a novel idea,
Subject of E-mail Message Indicating a Failed Provisional-Temporary Lock
Changes made to the database <YourDatabaseHere> 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 end of the message.
12
www.eVIEW.com
as developers have been doing this for years. In fact,

some of the core functionality of Lotus Notes involves
adding and removing backend note items. However,
when a developer uses Notes formula language,
LotusScript, or Java to modify the underlying data of
a note, the notes OID is modified and replication
needs to take place in order to synchronize document
instances between database replicas. By contrast,
when Notes/Domino 6 document locking adds or
removes items from the backend of a data note, the
notes OID does not change and the changes to the
document are not replicated. How, then, are document
lock statuses synchronized across multiple replicas?
Thats what well see next.
Propagating Lock Statuses to Other Replicas

When there is a current connection between the
requesting client or server and the master server, the
NRPCs that drive document locking move back and
forth in real time, while the user is attempting to lock
or unlock the document. If there is no connection to
the master lock server, this communication will not
take place until the next time the connection is made
and the master lock server and the remote server/client
replicate. Replication triggers the document-locking
calls between the master lock server and a remote
replica. Therefore, the NRPCs for document locking
are a by-product of the replication activity.
My testing bears this out. Locking/unlocking is
triggered by replication, but locking/unlocking synchronization happens independently of the replication activity.
Note!
You can use replication to trigger and synchronize
document locking, but you should not expect Notes
replication to always report that changes were
replicated.
Actually, I know two ways of triggering the

NRPCs required to promote or synchronize document
locking with the master lock server: replication and

opening a document on the remote client or server in
the UI in edit mode. The differences are these:
1. A replication-triggered NRPC will attempt to
synchronize all the outstanding document locks
between the two replicas.
2. Editing a document in the UI of the remote replica
will trigger the NRPC only for that document, no
others (as demonstrated in my testing).
Into Practice
Now that youve seen what the Notes/Domino
document-locking implementation is all about, its
time to get practical. Next, we turn to setup and administration and then to programming document locking.
Document Locking Setup

and Administration
Before document locking can be employed in a
database, you must do two things:
Configure the database for document locking, as

described below.
Ensure that the database landscape and replication

topology are set up properly to allow every replica
of the database (including remote replicas) to
communicate with the master lock server.
As the document-locking scenarios we looked at
earlier demonstrated, if any replica of a database
that has document locking enabled cannot communicate with the master lock server, document
locking may be compromised and user data may
be lost.
Configuring a Database for Document Locking

Since document locking was first introduced in Lotus
Notes/Domino 6, the databases for which you want
to enable document locking must have an on-disk
structure (ODS) of at least 43. I say at least because
13
Figure 10
The Allow document locking

Database Property
at the time of this writing, Lotus Notes/Domino version

7 beta 1 is available with the same ODS as Notes/
Domino 6; however, this may change with the release
of gold code.
Here are the steps to configure a database for
document locking:
1. Go to the Basics tab of the database Properties
window and select the checkbox Allow document
locking near the bottom of the window, as
shown in Figure 10. This action requires
Designer or higher-level access privileges in
the database access control list (ACL).
2. Define a Master Lock Server in the database
ACL. (The master lock server is also known as
the administration server, which should already
be defined for most databases.) This setting is
found at the top of the Advanced tab on the database ACL window, as shown in Figure 11. The
master lock server is a required setting, and it
Figure 11
14
The ACL Master Lock Server Setting
www.eVIEW.com
must be the same server for each replica of

the database, regardless of how many replicas
the database has or on what other servers the
replicas are placed.
3. While youre on the Advanced tab of the
database ACL, I also recommend selecting
Enforce a consistent Access Control List
across all replicas. This setting can help
prevent database replicas with incorrectly
defined master lock servers. Be aware, however,
that administrators who have Manager rights to
the database can circumvent this setting.
Application developers can try to code around

provisional locks to ensure that they are not used,
but since the Notes client UI menu contains lock and
unlock actions, there is no way to guarantee that a
rogue user will not defy the odds and provisionally
lock a document. Here are some strategies that can
help keep non-persistent locks to a minimum:
9 Educate your end users and management about
provisional locks, explaining their behavior and
the risks that they entail. If you can convince
your application stakeholders that a policy is
needed to avoid provisional locks, even better.
4. Ensure that the defined master lock server actually

has a replica of the database for which document
locking is being configured. The defined master
lock server must contain a replica of this database in order for document locking to work.
9 Avoid having an abundance of remote database

replicas. If you have remote replicas that do not
communicate regularly to the master lock server,
document locking in those remote replicas may
not function reliably.
Once the database settings have been

configured, document locking can and will attempt
to operate without any additional programming or
setup needed. As mentioned above, you will still
need to ensure that the database can communicate
with the master lock server.
9 Unless your Notes clients can reliably connect

to the master lock server and your users understand that a document might not be locked until
multiple replications have occurred (i.e., until
the master lock server has replicated with all
clients and servers that have replicas of the
database), avoid having local (Notes client)
replicas of a database with document locking
enabled in your environment. Allowing such
replicas is a recipe for help calls.
Administering Document Locking

Since document locking relies on functionality that
is intrinsic to Lotus Notes and Domino (replication,
Notes Object Service, Notes remote procedure
calls), it requires little additional maintenance.
Administrators simply need to monitor replication
and client communication, and document locking
will take care of itself.
Troubleshooting document-locking issues is
similar to troubleshooting replication or mail routing
issues. Document-locking issues are usually the
result of communication problems between a client
and server or between two servers.
Document Locking Strategy 101

In my experience, avoiding provisional locks is the
name of the game when it comes to optimizing
Dominos native document-locking functionality.
9 Tightening database ACL security can help

prevent provisional locks. By keeping users
with Editor access and above to a minimum,
you can reduce the chances of multiple users
simultaneously attempting to edit documents.
Important!
Make sure that the defined master lock server
has a replica of the database. As you saw, if
there is no replica on the master lock server,
only provisional locks will be created and users
will never be able to unlock documents regardless of whether the master lock server is available to the client.
15
Programming Notes/Domino 6
Document Locking in the
Notes Client
Since Lotus Notes/Domino version 6.0, programmers
have been able to use the Notes formula and
LotusScript languages to code solutions with document
locking. Java coding for document locking came with
the release of Notes/Domino 6.5. In the demonstration
database that accompanies this article, I provide
examples written in all three languages.
One of the most important aspects of programming
document locking is to provide an interface to allow
users to know the status of locked and unlocked
documents. Figure 12 shows you the view called
1. Main , which is one of the views in the demonstration database. This view displays the lock status
of documents. The first column of the view contains
a red or green icon to indicate document lock statuses
(red for locked, green for unlocked). In fact, users
can click on this status icon to trigger the document to
attempt document locking or unlocking. Documents
highlighted in red (dark gray) are persistently locked;
documents highlighted in yellow (light gray) are
provisionally locked.
To create this view, I used two view features
that are new in Notes/Domino 6: row custom color
Figure 12
16
formulas and the InViewEdit event of the LotusScript

NotesUIView class.
Row custom colors are an easy way to provide
programmatic row highlighting in Notes client views
based on document data. To change the row colors
when a document lock status changes, use row custom
color formulas, which are defined in view custom
color columns. Custom color columns are added to
views but hidden from users. When defined properly,
these formulas adjust the color of all columns to the
right of the defined color column in the view. Color
formulas, like other view column formulas, can be
based on document data.
I used the formula shown in Figure 13 in the
1. Main view to highlight the rows based on document
lock status. If a document is persistently locked, then
the row is highlighted with a red background and has
white text. If the document is provisionally locked,
the row is highlighted with a yellow background and
has black text. If the document is not locked at all,
then a white background with plain text, in this case
black, is used.
The InViewEdit event of the NotesUIView class
allows the documents in a view to be directly edited
from within the confines of the view, without opening
the document in the UI. In fact, the InViewEdit event
can actually expose editable fields resembling HTML
The 1. Main View Displays Document Lock Status
www.eVIEW.com
Figure 13
The View Column Formula for Custom Row Colors
red := 255:0:0;
white := 255:255:255;
yellow := 255:255:0;
black := 1:1:1;
plain:= 0:0:0;
@If(@IsAvailable($Writers); red:white;
@IsAvailable($PWriters) | @IsAvailable($PTWriters); yellow:black;
white:plain)
text inputs in the view columns. Then users can

edit documents in much the same way spreadsheets
are edited. Note: The InViewEdit feature is not
supported on the Web.
Coding the InViewEdit event is not trivial, as
there can be only one InViewEdit event for the entire
view. Columns that allow in-view editing must be
defined at design time. The InViewEdit event must be
written so that every editable column can be triggered
by the click of the mouse.
Figure 14
For the icons in the first column of the 1.Main

view, I used the InViewEdit event to run code that
toggles the document locks of selected documents.
When a user clicks on the red or green sphere icons,
the InViewEdit event fires and calls the toggle lock
code in a LotusScript library. Figure 14 displays the
code in the InViewEdit event of the 1. Main view.
This code uses the CaretNoteID property, which is
new in release 6, to get the note ID of the currently
highlighted document (the one at the caret location,
which is changed by the user clicking the mouse or
The InViewEdit Event Code
Sub Inviewedit(Source As Notesuiview, Requesttype As Integer, Colprogname As Variant, Columnvalue As

Variant, Continue As Variant)
'This view has one editable column
REM Define constants for request types
Const QUERY_REQUEST = 1
Const VALIDATE_REQUEST = 2
Const SAVE_REQUEST = 3
Const NEWENTRY_REQUEST = 4
REM Define variables
Dim db As NotesDatabase
Dim doc As NotesDocument
Dim ws As New NotesUIWorkspace
Dim caret As String
REM Get the CaretNoteID - exit if it does not point at a document
(continues on next page)
17
Figure 14 (continued)
caret = Source.CaretNoteID
If caret = "0" Then Exit Sub
REM Get the current database and document
Set db = Source.View.Parent
Set doc = db.GetDocumentByID(caret)
REM Select the request type
Select Case Requesttype
Case QUERY_REQUEST
REM Reserved - do not use for release 6.0
Case VALIDATE_REQUEST
REM Not used for icon columns
Case SAVE_REQUEST
REM Toggle document locks
Call toggleLock(doc)
Case NEWENTRY_REQUEST
End Select
End Sub
using the up and down arrow keys). With this

note ID, we can retrieve a document using the
NotesDatabase.GetDocumentByID method. The
retrieved document is then passed to the toggleLock()
sub, which will attempt to lock or unlock the document.
The code that toggles the locks is in the
libDocumentLocking library of the demonstration
database. You can see this code listed in Figure 15.
The code uses the NotesDocument Lock() and
UnLock() methods to toggle the document locks of
selected document objects, first checking to see if a
document is locked by looking at the NotesDocument
property, LockHolders. This property is an array of
all the users/groups that have the document locked.
18
If the LockHolders property is not empty, then

the code assumes that the document is locked and
calls the Unlock method, which takes no arguments.
If the LockHolders property is empty, then the
code assumes that the document is unlocked and
attempts to lock it by calling the Lock method.
This method offers programmers the option of
passing a string array argument that could be used to
populate the LockHolders property and the $Writers
or $PWriters items. Populating these items may be
useful to lock documents with multiple persons listed
as lock holders. This means that anyone listed in the
array would be able to unlock or edit the document if
www.eVIEW.com
Figure 15
The toggleLock Subroutine
Sub toggleLock(doc As NotesDocument)

If doc.LockHolders(0) = "" Then
Call doc.Lock(, False)
Else
Call doc.UnLock
End If
End Sub
needed. I chose not to pass in the array since locking

the document with a single lock holder is the most
reliable solution. The Lock() method simply defaults
to the current user executing the code.
for instances when a document holder is not available

and there is an urgent need to unlock the document.
The Boolean argument is also optional and

defaults to false. This argument controls whether or
not the Lock() method tries to apply a provisional lock
should the persistent lock operation fail to succeed. I
use the false argument here, because I feel there is no
need to use a provisional lock since the persistent
lock is the only safe lock to guard against data loss.
Document Locking on the Web
Document Locking Loophole
In the Notes client, when a user tries to edit a locked

document that he or she has not locked, the Notes
client complains (i.e., sends an NRPC to the master
lock server saying that the document is locked and
requesting it to be unlocked). The stateless environment
of the Web does not provide NRPCs to the master
lock server when a user requests to edit a document.
Moreover, the Web client does not have the functionality needed to stop users from editing locked documents
without added custom programming. If a Web user is
unaware that a document is locked and he or she edits
that document, the edits are lost and the Web server
could throw an ambiguous HTTP 500 error.
As youve seen, Domino locks documents by placing

items on the backend of the document note, which
means, of course, that theres a way to edit the items
directly without using the native methods provided
with the document locking API. A database user with
Manager or Author access and who is also a lock holder
can execute code to modify (or even remove or add)
the $Writers and $WritersDate items of a document,
thus effectively circumventing the entire documentlocking process. In the (RemoveLockItems) agent of
the demo database, I have provided a simple formula
to remove document-locking items. Of course,
performing such an operation results in the document
OID being changed and therefore requires a replication
to synchronize document instances between replicas.
This procedure could ultimately result in replication/
save conflicts and even lost data. It should be reserved
Until now, we have focused on document locking as

it works in the Notes client environment. I have
chosen to discuss how it works in Web environments
separately because while document locking works
well out-of-the-box in the Notes client, it does not
work as well for Web users.
Lotus is aware of this shortcoming and recommends

that developers employ WebQueryOpen code to alert
the user that a document is locked before the user
tries to edit it. For instance, you could create a
WebQueryOpen LotusScript agent that checks for
19
locked status before the document is edited on the

Web. The agent could then set values on the HTML
form that indicate the documents lock status. You
could use JavaScript or VBScript to check these values
and alert the Web user if the document is already locked.
Best Practice A Check-In/Checkout Process

A best practice for Web document locking is to
employ a check-in/checkout process. By forcing Web
users to check out a document before they edit it, you
can keep users from editing documents that they have
not yet checked out or locked. This practice is good
for the Notes client environment as well, as it avoids
the risks associated with provisional locks.
Figure 16
20
Figure 16 illustrates a simple Web interface

with check-in/checkout links to allow users to claim
documents before they can edit them. This view lists
documents, provides the links to check in or check
out documents, and by displaying lock holder information, indicates which documents are locked. The
links are created by adding formula language to compute
the values for the columns in the 1. Main Web
view and passthru HTML that is calculated to provide
either a check-in or checkout link. The code for creating
the links is listed in Figure 17.
The checkout link calls a LotusScript agent that
locks documents, and the check-in link calls an agent
that unlocks document. Figure 18 shows the code for
A Web Check-In/Checkout Interface
www.eVIEW.com
Figure 17
Column Formulas for Creating Web Links
check_out_link := "[<a href=\"/" + @WebDbName + "/(WebCheckOut)?openagent&" +

@Text(@DocumentUniqueID) + "&Login\">Check Out</a>]";
check_in_link := "[<a href=\"/" + @WebDbName + "/(WebCheckIn)?openagent&" +
@Text(@DocumentUniqueID) + "&Login\">Check In</a>]";
@If($Writers = ""; check_out_link; check_in_link)
Figure 18
The (WebCheckIn) Agent
Sub Initialize
On Error Goto ErrorHandler
Dim s As New NotesSession
Dim db As NotesDatabase
Dim view As NotesView
Dim doc As NotesDocument
Dim strUNID As String, strWebDbName As String
Dim varRet As Variant
Dim nnn As NotesName
varRet = Evaluate("@WebDBName")
strWebDbName = Cstr(varRet(0))
Set db = s.CurrentDatabase
Set doc = s.DocumentContext
strUNID = Left(GetQueryStringArgument(doc),32)
Set view = db.GetView("allbyunid")
Set doc = view.GetDocumentByKey(strUNID,True)
Call doc.unlock
If doc.LockHolders(0) = "" Then
Print |
<script>
//alert("Check-in failed, you do not have permission to unlock the document.");
top.location = "/| & strWebDbName & |";
</script>
21
|
Else
End If
ExitGracefully:
Exit Sub
ErrorHandler:
If Error$ = "Notes error: The document is not locked by you" Then
Set nnn = New NotesName(doc.LockHolders(0))
Print |
<script>
alert("Check-in failed, The document is currently locked by | & nnn.Abbreviated & |. You do not have permission to unlock the document.");
top.location = "/| & strWebDbName & |";
</script>
|
Else
Print "***Error: " & Str(Err) & " : " & Error$
End If
Resume ExitGracefully
End Sub
the (WebCheckIn) agent. The link for this agent forces

the Web user to log in before the agent is executed,
and the agent is set up to run as the Web user. This
agent first tries to unlock the document. If this attempt
fails, either because the user is not the explicit lock
holder or because the user is not in a group that is
listed as the lock holder, a JavaScript alert box notifies
the user that he or she doesnt have permission to
unlock the document and presents the user with the
identity of the lock holder.
22
Lock Decay
Document locking raises the possibility of forgotten
locked documents. If a document is locked by an end
user and he or she neglects to act on it or unlock it in
a timely manner, then other users continue to be
restricted from editing the locked document and the
document is considered to be stagnant. This situation
can lead to database managers receiving late-night
requests to manually unlock stranded locked documents.
www.eVIEW.com
Lock decay is the solution that can prevent this

scenario. Simply put, lock decay is the process that
unlocks documents after a certain amount of time
has passed, when we can assume that they no longer
need to be locked or that they have been forgotten or
abandoned by the original lock holder(s).
With the appropriate lock decay policy and
implementation, you can avoid stalled document
workflows in your business applications. Unfortunately,
lock decay is not currently implemented in Notes/
Domino 6. Once a document is manually or programmatically locked with a persistent lock, the document
could remain locked indefinitely.
Since this much-needed functionality never made
it into the final product, developers and administrators
must provide their own lock decay solution. I recommend incorporating the following principles into your
solution:
To avoid stagnant locks on documents, define

business practices for informing all users how
long a document can remain locked and not
Figure 19
actively edited before the lock on the document

is decayed.
Any lock decay functionality should be underpinned

by the $Writers and the $WritersDate items that
are used by the built-in Notes/Domino 6 document
locking mechanism.
It may also be worthwhile to monitor the lastmodified property of the document to help determine
when a document entered a stagnant state.
The lock decay solution should notify the lock

holder(s) of a document whose lock has decayed.
In the demonstration database that accompanies

this article, I provide a lock decay solution that
decays locked documents based on the $WritersDate
item and Last Modified property of the locked document.
Use the Lock Decay Config form to create a lock
decay profile that can be used for all users or for
certain roles listed in the ACL.
Figure 19 shows a Lock Decay Config
document that pertains to the [Test] role of the
A Lock Decay Config Document
23
sample database. Figure 20 defines the settings in

this document.
Create a Lock Decay Config document for each
role in the database ACL, being sure to assign a
Weight value for each role. The Weight value will be
used to determine the configuration document whose
settings should be used when there are multiple Lock
Decay Config documents that might apply to the user.
Also create a document called ALL that has a very
low Weight value. The settings in the ALL document
will apply when another, higher-weighted document
does not match a role that the user has.
The core of this lock decay solution is the
LotusScript Lock Decay agent, which is set in the
download database to be called manually from the
Actions menu, but which you will probably want to
set up as a scheduled agent. This agent begins by
initializing a custom logging routine to create an audit
trail of when and why document locks were decayed.
Next, the agent calls the processLocks subroutine,
which generates a list of all of the Lock Decay Config
documents and their weighted values, organized into
LotusScript lists. A list of NotesACLEntry elements
is also created by the processLocks subroutine to be
used in later processing.
Figure 20
Then the LotusScript Lock Decay agent iterates

through all the locked documents in the vwUserLocks
view and compares the value of the LockHolders
property to the ACL entries. If a lock holder is listed
in the ACL explicitly, then the users roles are checked
against those roles listed in the Lock Decay Config
documents (Figure 21 shows the code). This part of
the agent processing also checks for the [NoDecay]
role for the lock holder; if the lock holder has this
role applied in the database ACL, then the process
skips this locked document.
When the agent finds multiple Lock Decay Config
documents that can be applied to a lock holder, the
document with the highest weighted value takes
precedence over all others. If the lock holder does not
belong to roles that have associated Lock Decay Config
documents, then the Lock Decay Config document
for ALL users is applied (see Figure 22).
When a lock holder is not explicitly listed in the
database ACL, then the agent must determine how the
ACL is applied to the lock holder. To accomplish
this, the agent must search through groups in the
Domino Directory (or NAB, for you old-timers) to
determine not only which group the lock holder
resides in, but also how that group is entered in the
Settings in the Lock Decay Config Document
Setting
Definition
$WritersDate Decay (#, Unit)
Indicates the time that must pass after a document is locked before it can
be decayed
Last Modified Decay (#, Unit) Indicates the time that must pass after a document is modified before the lock
can be decayed
Send Message
Indicates (Yes or No) whether a message is to be sent to the lock holder(s)

when the document lock is decayed
Message Text
Contains the message that will be sent to the lock holder(s)
Include DocLink
Includes a link to the decayed document in the e-mail message
Decay Users
Indicates the users that this profile applies to
Roles
Indicates what roles this profile should apply to (if roles have been selected)
Weight
Indicates the weighted value for this document (used to determine the configuration
document whose settings should be used when there are multiple Lock Decay
Config documents)
24
www.eVIEW.com
Figure 21
Code to Check User Roles Against Lock Decay Config Documents
Do While Not (doc Is Nothing)

strUser = doc.LockHolders(0)
boolFlag = False
Forall entries In aclList
If Listtag(entries) = strUser Then
Forall r In entries.Roles
If r = NO_DECAY Then
Call logger.logactivity("[NODECAY] document (" & doc.UniversalID & ") for " & strUser)
Goto SkipDocument
End If
If Iselement(roleWeight(r)) Then
If strRole = "" Then
strRole = r
Else
If roleWeight(strRole) < roleWeight(r) Then
strRole = r
End If
End If
boolFlag = True
End If
End Forall
End If
If boolFlag Then
If checkDecay(docList(strRole), doc) Then
decayList(doc.UniversalID) = docList(strRole).universalid
Call logger.logactivity("[DECAY] decaying document (" & doc.UniversalID & ") for " & strUser &
" using role " & strRole)
End If
Exit Forall
Else
If checkDecay(docList("ALL"), doc) Then
decayList(doc.UniversalID) = docList("ALL").universalid
". Using ""ALL"" settings for -Default- user")
End If
End If
End Forall
Figure 22
Applying Lock Decay Settings for ALL Users
If checkDecay(docList("ALL"), doc) Then

decayList(doc.UniversalID) = docList("ALL").universalid
". Using ""ALL"" settings for -Default- user")
End If
25
ACL. This could mean processing multiple nested

groups, so I use the recursive function shown in
Figure 23, which gets group membership information
from the ($ServerAccess) view in the Domino
Directory.
The getGroups() function processes all of the
groups that a lock holder belongs to and all of the
groups that those groups may be nested in, while
drilling down through several layers of the nested
group hierarchy. It creates a list of all the associated/
nested groups and returns that list to the calling function,
which then compares each group to the ACL entries
and checks the groups roles against the settings in the
Lock Decay Config documents.
The Lock Decay agent applies a Lock Decay
Config document to a lock holder by executing the
checkDecay() function, which simply adds a list
element to the decayList, where the element is the
UNID of the Lock Decay Config document and the
list tag is the UNID of the actual locked document.
At this time, the agent also adds a log entry that
Figure 23
indicates why the document lock is being decayed

and what user, group, and lock decay settings have
been used. Figure 24 shows a typical log document.
Later, the agent uses the decayList and calls the
docDecay() function for each locked document that
needs to be decayed (see Figure 25).
Design Element Locking

With the ever-increasing likelihood that teams of
application developers may be working on the same
applications across long distances and multiple
servers, there is a need to manage conflicts among
developers working on the same design elements.
Design elements are simply Notes documents (notes)
that represent database design components. Unlike
data notes, however, design notes do not create conflict
documents. If a save or replication conflict occurs
with a design note, the loser of the conflict loses
his or her changes.
The Recursive Function getGroups( )
Function getGroups(strName As String) As Boolean

getGroups = False
Dim groupdoc As NotesDocument
Dim dc As NotesDocumentCollection
Set dc = vwAccess.GetAllDocumentsByKey(strName, True)
If dc.Count > 0 Then
getGroups = True
Set groupdoc = dc.GetFirstDocument
Do While Not (groupdoc Is Nothing)
strGroups(groupdoc.ListName(0)) = groupdoc.ListName(0)
Call getGroups(groupdoc.ListName(0))
Set groupdoc = dc.GetNextDocument(groupdoc)
Loop
End If
End Function
26
www.eVIEW.com
Figure 24
A Typical Log Document of Lock Decay Execution
Figure 25
The docDecay( ) Function
Forall unids In decayList

Call docDecay(unids, Listtag(unids))
End Forall
Function docDecay(cfgUNID As String, lockUNID As String) As Boolean

docDecay = False
Dim strWho As String
Dim cfgdoc As NotesDocument, lockdoc As NotesDocument
Set cfgdoc = vwUNID.GetDocumentByKey(cfgUNID,True)
Set lockdoc = vwUNID.GetDocumentByKey(lockUNID,True)
strWho = lockdoc.LockHolders(0)
Call lockdoc.UnLock
docDecay = True
If cfgdoc.radMsg(0) = "1" Then
Dim strMsg As String
Dim memo As NotesDocument
Dim rti As NotesRichTextItem
27
strMsg = cfgdoc.txtMsg(0)
Set memo = db.CreateDocument
memo.SendTo = strWho
memo.Subject = "Your document has been decayed."
Set rti = New NotesRichTextItem(memo, "Body" )
Call rti.AppendText(strMsg)
Call rti.AddNewline(1, True)
If cfgdoc.radLink(0) = "1" Then
Call rti.AppendDocLink(lockdoc, "Previous Locked Document")
End If
Call memo.send (False)
End If
End Function
Notes/Domino 6 design element locking is a

built-in tool that you can use on any database that
will be developed by multiple developers. With some
exceptions, the same back-end items are used to lock
design elements that are used to lock Notes documents.
Like document locking, design element locking requires
that a master lock server be set in the database ACL.
The second database-level requirement is that the
Allow design locking property must be checked
on the Design tab of the database properties.
Notes/Domino design locking has the same
topology requirements and characteristics as
document locking:
9 Persistent locks are the only safe locks.

9 Provisional locks can be promoted to persistent
locks.
9 NRPCs are used to communicate with the master
lock server to lock design notes.
9 Replication can be used to trigger lock promotion
and synchronization.
9 Developers can lock or unlock design elements
manually while the master server is available.
9 The master lock server must be available for

communication with any server or client that is
attempting to use persistent locking.
Despite the similarities between document locking

and design element locking, there are notable differences.
If a persistent lock is applied to a design element, then
the $Writers and the $WritersDate items are added to
the design note and a padlock icon is displayed in the
left margin of the design element list as an indicator
(see Figure 26). Padlock icons are characteristics
only seen with design element locking.
Design locking also has the same characteristics

as document locking:
If the design element has a provisional lock applied,

then the $PWriters item is added to the design note
9 The defined master lock server must have a

replica of the database.
28
www.eVIEW.com
and a padlock with an arrow is used as the

indicator icon.
mention the use of provisional locks, but it does

mention that the master lock server is not available.
I noticed another difference in how automatic

design element locking works while testing this
functionality in the Notes/Domino 6.5 client with a
6.5 server. When a design note is opened in the
Domino Designer client and the master lock server is
available, the design element is automatically locked
and the correct items are written to the backend of the
design note. When the design note is closed in the
UI, the items disappear from the design note.
However, when the master lock server is unavailable
and a design element is opened in Domino Designer,
the behavior is not congruent with the document locking conventions we saw earlier.
In this situation, I observed no back-end items

written to the design note, which means that a
provisional lock is the only type available. I
would not consider this option for editing design
elements.
First, you are presented with the modal dialog

shown in Figure 27. Note that this dialog does not
Figure 26
Another unique behavior of design locking is the

one I observed when I tried to edit the Help About
and Help Using this Database documents found in
the Database resources. It appears that these design
elements do not automatically lock when they are
edited. They cannot be edited and saved, however,
without first locking them manually. If I tried to
edit the documents without first locking them, I
could not save my edits and I would be notified by
a Notes pop-up that I had to first lock the document.
Persistent and Provisional Locks on Design Elements
Figure 27 Dialog for Editing a Design Note When the Master Lock Server Is Unavailable
29
Figure 28
The Developer Must Lock Help

Documents Before Editing and
Saving Them
Figure 28 shows the message I received when I

tried to save the document. Figure 29 shows the
message I received when I tried to save the document
in response to the prompt during the QueryClose
event of the document.
Design Locking and WebDAV
Figure 29
The Developer Cannot Save

This Help Document Without
First Locking It
One of the key uses for design locking is apparent

when we consider WebDAV, Web-based Distributed
Authoring and Versioning. WebDAV is an IETF
(Internet Engineering Task Force) standard, a set of
extensions to the HTTP protocol, which allows users
to collaboratively edit and manage files on remote
Web servers (www.webdav.org).
With WebDAV, non-Domino developers can edit
Domino design elements (File, CSS, and Image
resources) from outside the Domino database and
server, without the Domino Designer client.
In fact, using mainstream Web tools such as
Macromedias Dreamweaver MX, Web developers
can actually check out design elements and lock them
in the Domino database while they edit them. Design
locking is a requirement for WebDAV operations.
Figure 30
Document Locking Concerns

in a Mixed Environment
Scenario
Outcome
R5 client trying
to edit a locked
document
Client generates an error

message on save: Cannot
save edits.
Notes/Domino 6
client trying to
edit a document
on an R5 server
The following error message

displays: Server does not
support this version of the
network protocol.
Note: Your Notes/Domino 6

client will have the menu option
to Lock/Unlock, but the server
is not able to support that call.
Mixed R5 and Notes/Domino 6

Environments
According to Lotus, there are several things to be
aware of if your environment includes older versions
of Notes/Domino and you are using Notes/Domino 6
document locking. Figure 30 lists these concerns, as
outlined in Notes documentation.3
Best Practices
In this section, I gather up the recommendations and
best practices for document locking that were provided
30
See http://www-1.ibm.com/support/
docview.wss?rs=0&q=7003259&uid=swg27003259
www.eVIEW.com
throughout the article, together with a few new ones,

and present them in one easy-to-reference list.
9 Avoid provisional or provisional-temporary
locking.
-
Where possible, employ application design

techniques to help provide check-in/checkout
functionality as an alternative to provisional
document locks.
locks will be created and users will never be able

to unlock documents regardless of whether the
master lock server is available to the client.
9 Provide check-in and checkout for Web users.
In certain circumstances (e.g., remote users),
provide this functionality for Notes client users
as well.
9 Keep users informed.
Educate users about the dangers of provisional

locks.
Let users know the status of documents

through UI components such as views and
computed text.
For users with a remote replica and dial-up or

VPN connection that is not always connected
to the master lock server, suggest that they try
to connect to the Domino server and initiate
an NRPC (through replication or some other
means) to try to lock a document before they
make edits to it.
Users should understand that if they edit

documents under a provisional or provisionaltemporary lock, their changes will not be
preserved if someone else has the document
persistently locked.
Users should also should know that the

e-mail message they receive from Notes
when provisional locks are not promoted is
somewhat unreliable and could cause them
to lose their edits.
9 Grant Editor access and above to as few users

as possible, restricting general users of the
database to Author. This practice is almost
always a good idea, regardless of whether or not
document locking is enabled. By keeping the
number of potential editors to a minimum, you
reduce the chances of multiple editors attempting
to edit a document simultaneously.
9 Inform users with Manager access to exercise

caution. If they use their authority to unlock a
database document and edit it, they could cause a
conflict condition.
9 Design views and forms that make the user

aware of document-locking status.
9 Consider using custom lock decay functionality.
Even though its not intrinsically part of document
locking, lock decay should be considered a necessity
for any application manager or administrator who
does not want to have stagnant locked documents
and calls from frustrated users in the small hours
of the morning.
9 Plan your database locking strategy around
sound server availability and replication setup.
If the master lock server cannot be reached, persistent locks cannot be created and editing will be
unreliable.
9 Make sure that the defined master lock server
has a replica of the database. If there is no
replica on the master lock server, only provisional
Notes/Domino 6 Document
Locking and Design Locking
in a Nutshell
Document locking comes built-in with Lotus
Notes/Domino version 6.0 and above. Out-of-the-box
functionality requires no additional development and
provides a clean solution for record locking in a Lotus
Notes client environment provided that the master
lock server is readily available for replication and
NRPC communication with clients and other servers.
To use document or design locking, the master lock
server must have a replica of the database.
Lotus provides programmability of document
locking using the Notes formula and LotusScript
31
languages in release 6.0 and, as of Notes/Domino 6.5,

the Java API, which is great because effective document
locking for Web users requires custom solutions.
Design locking is document locking for design
notes and works much the same way as document
locking with a few minor exceptions. Design locking
is a requirement if applications will be accessed via
WebDAV clients.
To implement many of the best practices and
recommendations made in this article, I invite you
to use the solutions provided in the database at
www.eVIEW.com.
32
James Ray has been working with Notes since

release 3.3. He specializes in enterprise integration
with Oracle and SAP, Web development, and
Notes/Domino 6 migrations. He is a Principal
Certified Lotus Professional (IBM Certified
Advanced) System Administrator and Application
Developer for Notes and Domino releases 4, 5,
and 6. James is also an IBM Certified Associate
System Administrator for Lotus QuickPlace 3, as
well as a Microsoft Certified Systems Engineer
(MCSE). In addition, he has worked with Lotus
education in developing exam content, including
the Notes and Domino 6 update exams for
administration and application development, as
well as the administration exam for the Domino 6
server. James has written for several professional
publications and has been a speaker at multiple
conferences for THE VIEW. You can contact him
at jimmyraywv@yahoo.com.
www.eVIEW.com

A Guide To Document Locking in Notes/Domino 6

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

A Guide To Document Locking in Notes/Domino 6

Hochgeladen von

Copyright:

Verfügbare Formate

A Guide to Document Locking in Notes/Domino 6

The new document locking functionality in Notes/Domino 6 has been

James Ray specializes in

Most software users are familiar with the concept of document or

(complete bio appears on page 32)

THE VIEW September/October 2004

Ive created a demonstration Notes/Domino 6.5

9 LotusScript code to apply and remove locks using

In Notes/Domino 6, document locking is the process

9 Formula code to remove lock items from a

At www.eVIEW.com, click THE VIEW Journal > Download Files >

A race condition (or hazard) is deviant behavior that occurs in a process

libMisc LotusScript library that houses

2004 THE VIEW. All rights reserved.