im lock

im lock locks a document item for editing. Locking a document for editing prevents others from editing particular fields of that document.

You can lock a document as an individual or for a group that you belong to. When no --asgroup option is specified, im lock assumes that you are attempting to lock the document for the current user. To successfully lock a document, the administrator must have defined the document type as one which uses locking and you must meet the criteria set by the administrator as to who is eligible to lock documents of that type.

The administrator also defines which fields in a given document type (and its content items) are protected by locking. These are called lockable fields. The list of lockable fields for any given document type always includes, at a minimum, the significant fields for that type.

Locking is not recursive. When you lock a document, only that document is locked. Subdocuments of that document are not locked.

You can lock a document as either an individual user or as a group. When a document is locked by an individual user, only that user can edit the lockable fields of that document. When a document is locked by a group, only members of that group can edit those fields.

Normally, when a document is not locked, any user can edit the lockable fields of that document. However, the administrator can configure Windchill RV&S to require users to lock a document before they edit the lockable fields of that document. When such a requirement is in place, no one can edit the lockable fields of an unlocked document.

The requirement to lock a document before editing it is rule-based. As a result, it may not be in effect at all times or all documents of the given document type.

You can view the lock information about any document or content item with the --showLock option of the im viewissue command.

The following issues apply to working with locked documents:

• Users with a lock on a document (either individually or as part of a group) can perform all document model operations that they have permission for. Users without a lock cannot perform any document model operations on the locked document, including versioning.

The structure field is a significant field. As a result, when a document is locked, users or groups without a lock cannot make structural changes to that document.

• The reference mode of a content node is independent from locking. It does not matter whether the mode is Share, Reuse, or Author because the document and content items are locked not the shared items.

• When you add new content to a locked document, the new content is locked immediately with the same lock attributes as the rest of the document.

• When you include or insert another document in a locked document, the referenced document is not locked but the content item referencing the including or inserted item is locked.

• You cannot lock a versioned document; however, you can version a locked document.

• Any user can copy content from a locked document. If locked content is pasted into another unlocked document, the paste content is now unlocked.

• When a content item is removed from a locked item, that content item becomes unlocked.

• Locking is not a historical operation. Viewing items historically does not show any lock information. Similarly, locking and unlocking operations do not appear in the history information of an item.

Field relationships (constraints) as well as editability and relevance rules still apply to locked documents. When a field relationship is such that the target field is a lockable field in a locked document, a user without a lock cannot modify the source field to invalidate the target field.

For example, the current user is a member of the group Reviewers. Consider the following documents:

• Document 100 is a Windchill RV&S document of a type that uses locking and can be locked by anyone. Locking is not required to edit this document.

• Document 200 is a Windchill RV&S document of a type that uses locking and can be locked by members of the Authors, Reviewers, and Publishers groups. Locking is required to edit this document.

• Document 300 is a Windchill RV&S document of a type that uses locking and can be locked by members of the Publishers group. Locking is not required to edit this document.

attempts to lock Document 100 for the current user. This succeeds because the document type can be locked by anyone. Once this document is unlocked, any user can edit the lockable fields of this document.

im lock --asgroup=Reviewers 200

attempts to lock Document 200 for the Reviewers group. This succeeds because the current user belongs to the specified group. When this document is unlocked, no user can edit the lockable fields of this document.

attempts to lock Document 200 for the current user. Once again, this succeeds because the current user belongs to one of the groups who can lock this document type. When unlocked, no user can edit the lockable fields of this document.

attempts to lock Document 300 for the current user. This fails because the current user is not a member of the Publishers group, which is the only group that can lock documents of this type.

presents a dialog that the prompts the user to select the desired locking options and locks Document 100 using the specified options.

This command takes the universal options available to all im commands, as well as some general options. See the options reference page for descriptions.

When you do not specify this option, im lock attempts to lock the document for the current user.

the ID of the document you are locking. To specify multiple documents, use a space separated list. All specified documents must be of the same type.