Managing Locks in Revit Server

Three different types of lock are used to maintain data integrity in server-based worksharing:

• Element-level locks, which restrict access such that an element can only be modified by one user at a time
• Model-level locks, which restrict access to (and therefore protect) model data during specific stages of certain operations
• Administrator-level locks, which facilitate server and server data maintenance

Element-Level Locks

Element-level locks control access to each element when multiple users are working in the same model. They are used in both the file-based and server-based workflow and behave according to the following rules:

• An element can only be owned by one user at a time.
• Element locks are associated with Revit users via Revit usernames.
• An element can only be modified by the user who owns it; all other users are locked out.
• A user can only surrender ownership of unmodified elements.
• Changes to modified elements must be committed to the central model or abandoned entirely before ownership can be relinquished.

Element-level locks are acquired by checking out a workset, by explicitly borrowing an element, or by editing an element directly. They can be released when a user performs a Synchronize with Central, and they are always released on the completion of a Relinquish All Mine operation.

In the server-based workflow, element-level locks are maintained in a collection of SQLite databases. For example, element-level locks acquired without the use of worksets are stored in the file ElementPermissions.db3:

Because element-level locks are associated with users by Revit username (and not by a specific instance of Revit, a particular workstation, or a network user account,) Revit Server will treat two individuals with the same Revit username as a single user. In this case, each would be allowed to modify the same element at the same time, which could result in data loss and model corruption. Therefore, every user collaborating through Revit Server should be sure to choose a unique Revit username.

In some cases it may be acceptable to assume the identity of another user by intentionally adopting that user’s Revit username: If a user must modify an element that is locked by another user, and that user is not available to relinquish it, an administrator can temporarily assume that user’s identity and release the lock. Note that this could render that user’s local copy irreconcilable with the central model, potentially resulting in the loss of data. Therefore, whenever feasible, it is preferable for the original creator of the lock to relinquish the element.

Model-Level Locks

Used in both file-based and server-based worksharing, model-level locks are created by Revit during certain operations to restrict access to the central model when concurrent access could jeopardize data integrity. The locks are automatically released when these same operations complete successfully and should not require manual intervention.

Administrator-Level Locks

The administrator-level lock applies only to server-based worksharing, as it is used to facilitate Revit Server Host maintenance operations where activity in a model (or a collection of models) should be halted. For example, a model’s state should be frozen before the model is archived. Failure to do so could result in an archived copy containing partly committed changes from an update, and this copy would be unusable. If an administrator-level lock is applied first, the model state is guaranteed to be quiescent, and this pitfall can be avoided.

An administrator-level lock is applied using the Revit Server Administrator web-based management utility (or its command-line utility counterpart). The lock can be applied to an entire Revit Server Host, all the models in a folder, or a single model.

To apply an administrator-level lock to an item

1. Open the Revit Server Administrator.
2. In the tree control, select the item, and click (lock).
   Note: If you use the command-line utility to apply a lock, the lock icon displays after a refresh operation, and information about the model in use displays in the right pane.

When an item is locked:

• The lock symbol displays to the right of the (server, folder, or model) icon.
  
• All parent folders of a locked folder display an icon that indicates they contain locked items.
• Child folders are also locked.
• Revit blocks any operation requiring access to the item and informs the user that the central model is locked.

The lock is actually applied in 2 stages. First, all in-progress operations are allowed to continue while new ones are blocked. When the in-progress operations have all completed, the lock is fully committed and further access is unconditionally blocked until the lock is released.

Administrator-level locks rarely require any kind of manipulation. However, if there are any malformed central models (perhaps because a first-time save of a new central model failed), Revit Server may not be able to properly create or release an administrator-level lock. In this case, the lock can be removed by deleting the super.lock file from the Revit Server Host’s root project storage directory. (Note that the offending malformed model should also be removed to prevent the problem from reoccurring.)

Best Practices for Working with Locks

Locks are intended to be transparently managed and maintained by the system. Observing the following guidelines can help to ensure a positive user experience when collaborating across geographically dispersed sites using Revit Server.

• Ensure all users have unique Revit usernames.
• Do not terminate Revit while it is in the middle of an operation.
• If an operation fails, immediately retry it (after restarting Revit if necessary).
• If first-time save of a new central fails, alert the administrator so that the malformed model can be removed.