IRPCObjectOperations.CheckOut

Vault API / core write session or assertion returns metadata structure version

Checks out one object.

Service	Objects, versions, properties and files `MFiles.IRPCObjectOperations`
gRPC method	`/MFiles.IRPCObjectOperations/CheckOut`
HTTP (mf-http-grpc)	`POST /grpc/v1/check-out`
Request	`CheckOutRequest`
Response	`CheckOutResponse`
Book and level	Vault API, core
Kind	write
Session	Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
Idempotent	no
Returns metadata structure version	yes (in the mfiles-metadata-version-bin trailer)
Streaming	none (unary)

Remarks

Checking out creates a new version (latest checked-in version + 1) that only the caller can change. GetLatestObjectVersion returns the checked-out version only with allow_checked_out: true. The check-out is bound to the user and to the computer name of the session, which is environment_data.client_name of the LogIn call: another session of the same user with a different client_name fails with "The object was checked out to another computer (<name>)."

Errors: "The object is already checked out." if the caller already has it checked out, "The object is checked out to another user." if someone else does.

You rarely need CheckOut for metadata changes: SetProperties with allow_modifying_checked_in_object checks out, changes and checks in in one call. Check out explicitly to make several changes (properties and files) into one new version.

Request: CheckOutRequest

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

Field	Type	Description
`obj_id`	`ObjID`	The object to check out. The latest checked-in version is checked out.
`obj_id.type`	`int32`	The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID).
`obj_id.item_id`	`ItemID`	The ID of the object within its type, in `item_id.internal_id`.
`obj_id.item_id.internal_id`	`int32`	The ID of the object or value list item.
`obj_id.item_id.external_repository_id`	`ExternalRepositoryID`	Used only for objects in external repositories (external connectors). Leave it unset for objects stored in the vault.

Response: CheckOutResponse

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

Field	Type	Description
`object_info`	`ObjectVersionExWP`	The checked-out version: its version number is the one to pass to SetProperties, AddObjectFile and CheckIn.
`object_info.object_version`	`ObjectVersionEx`	Object info.
`object_info.object_version.version_info`	`ObjectVersion`	Object Version information.
`object_info.object_version.object_info`	`ObjectLevelInfo`	Object-level information.
`object_info.properties[]`	repeated `PropertyValue`	Property values, or an empty array.
`object_info.properties[].property_def`	`int32`	The property definition ID, for example 0 for "Name or title" or 100 for "Class".
`object_info.properties[].value`	`TypedValue`	The value. Its `type` must match the data type of the property definition.
`object_info.acl`	`AccessControlList`	If set, ACL.
`object_info.acl.checked_out_to_user`	`int32`	Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist.
`object_info.acl.is_fully_authoritative`	`bool`	Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version.
`object_info.acl.custom_component`	`AccessControlListComponent`	Accesses the custom component of this ACL.
`object_info.acl.restrictive_components[]`	repeated `AccessControlListComponentMapEntry`	Accesses the restrictive automatic components of this ACL.
`object_info.acl.secondary_access_control_list`	`AccessControlList` (recursive)	Secondary ACL used for latest version ACL. Not used for access check if null.
`object_info.acl.additive_components[]`	repeated `AccessControlListComponentMapEntry`	Accesses the additive automatic components of this ACL.
`object_info.current_user_permissions`	`ObjectPermissionsForClient`	If set, permissions of the object version.
`object_info.current_user_permissions.can_user_see`	`bool`	The object is visible for the current user (provided for symmetry).
`object_info.current_user_permissions.can_user_edit`	`bool`	The current user can edit the object.
`object_info.current_user_permissions.can_user_delete`	`bool`	The current user can delete the object.
`object_info.current_user_permissions.can_user_change_permissions`	`bool`	The current user can change the object permissions.
`previous_version`	`ObjectVersionEx`	The checked-in version the check-out started from.
`previous_version.version_info`	`ObjectVersion`	Object Version information.
`previous_version.version_info.version`	`ObjVerVersion`	The version number, as a specific version.
`previous_version.version_info.display_version`	`string`	The version label to show, if it differs from the version number; empty otherwise.
`previous_version.version_info.title`	`string`	The title (name) of the object in this version.
`previous_version.version_info.is_single_file_object`	`bool`	True if the object is a single-file document, which has exactly one file.
`previous_version.version_info.has_relationships_from_this`	`bool`	Note: this field is deprecated. True if relationships from this object version to one or more documents exist.
`previous_version.version_info.has_relationships_to_this`	`bool`	Note: this field is deprecated. True if relationships from one or more documents to this object version exist.
`previous_version.version_info.has_assignments`	`bool`	True if relationships from one or more assignments to this object version exist.
`previous_version.version_info.last_modified_at_utc`	`google.protobuf.Timestamp`	When the version was last modified, in UTC.
`previous_version.version_info.files[]`	repeated `File`	The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`.
`previous_version.version_info.object_version_flags`	`OBJVERFLAGS`	Bit flags that provide additional information on the object version.
`previous_version.version_info.class_id`	`int32`	The class ID of the version.
`previous_version.version_info.version_guid`	`string`	The GUID of this version.
`previous_version.version_info.base_properties[]`	repeated `PropertyValue`	Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`.
`previous_version.version_info.primary_file`	`FileID`	File ID of the primary file of a multi-file object, if the object is a multi-file object.
`previous_version.object_info`	`ObjectLevelInfo`	Object-level information.
`previous_version.object_info.obj_id`	`ObjID`	The object type and ID of the object.
`previous_version.object_info.external_id_status`	`ExtIDStatus`	The status of this object's external ID.Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5).
`previous_version.object_info.external_id`	`string`	The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID.
`previous_version.object_info.checked_out_version`	`ObjVerVersion`	The version that is checked out. Version number 0 if the object is not checked out.
`previous_version.object_info.checked_out_to_user_id`	`int32`	The ID of the user who has the object checked out.
`previous_version.object_info.checked_out_to_user_name`	`string`	The user name of the user who has the object checked out.
`previous_version.object_info.checked_out_to_host_name`	`string`	The host name of the computer to which the object was checked out.
`previous_version.object_info.checked_out_at_utc`	`google.protobuf.Timestamp`	The timestamp of the moment the object was checked out.
`previous_version.object_info.checked_in_version`	`ObjVerVersion`	The latest checked-in version.
`previous_version.object_info.created_at_utc`	`google.protobuf.Timestamp`	The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue).
`previous_version.object_info.accessed_by_me_utc`	`google.protobuf.Timestamp`	Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back.
`previous_version.object_info.guid`	`string`	The object GUID, in braces. The same value as `GetObjectGUID` returns.
`previous_version.object_info.options`	`ITEMFLAGS`	Bit flags that provide additional information on the object (e.g. is the object deleted or a stub).
`previous_version.object_info.original_vault_guid`	`string`	The GUID of the vault in which the object was originally created.
`previous_version.object_info.original_vault_obj_id`	`ObjID`	The original objid in the vault in which the object was originally created.
`previous_version.object_info.associated_view_id`	`ItemID`	Identifies the view associated with this object if any.
`previous_version.object_info.external_repository_icon_id`	`string`	If not null, identifies the icon of the object. Currently applicable only to unmanaged objects.
`previous_version.object_info.primary_view_id`	`ItemID`	If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects.
`previous_version.object_info.capabilities`	`OBJECTCAPABILITYFLAGS`	Bit flags that provide information on the object capabilities.
`updated_objects[]`	repeated `ObjectVersionEx`	Information about objects that were also updated during the operation. (represented by ObjectVersionEx structs.)
`updated_objects[].version_info`	`ObjectVersion`	Object Version information.
`updated_objects[].version_info.version`	`ObjVerVersion`	The version number, as a specific version.
`updated_objects[].version_info.display_version`	`string`	The version label to show, if it differs from the version number; empty otherwise.
`updated_objects[].version_info.title`	`string`	The title (name) of the object in this version.
`updated_objects[].version_info.is_single_file_object`	`bool`	True if the object is a single-file document, which has exactly one file.
`updated_objects[].version_info.has_relationships_from_this`	`bool`	Note: this field is deprecated. True if relationships from this object version to one or more documents exist.
`updated_objects[].version_info.has_relationships_to_this`	`bool`	Note: this field is deprecated. True if relationships from one or more documents to this object version exist.
`updated_objects[].version_info.has_assignments`	`bool`	True if relationships from one or more assignments to this object version exist.
`updated_objects[].version_info.last_modified_at_utc`	`google.protobuf.Timestamp`	When the version was last modified, in UTC.
`updated_objects[].version_info.files[]`	repeated `File`	The files of this version. Each `file_ver` can be passed to `DownloadFile_Begin`.
`updated_objects[].version_info.object_version_flags`	`OBJVERFLAGS`	Bit flags that provide additional information on the object version.
`updated_objects[].version_info.class_id`	`int32`	The class ID of the version.
`updated_objects[].version_info.version_guid`	`string`	The GUID of this version.
`updated_objects[].version_info.base_properties[]`	repeated `PropertyValue`	Not filled by the object read methods; read the property values with `GetObjectVersionAndPropertiesOfMultipleObjects` or `GetProperties`.
`updated_objects[].version_info.primary_file`	`FileID`	File ID of the primary file of a multi-file object, if the object is a multi-file object.
`updated_objects[].object_info`	`ObjectLevelInfo`	Object-level information.
`updated_objects[].object_info.obj_id`	`ObjID`	The object type and ID of the object.
`updated_objects[].object_info.external_id_status`	`ExtIDStatus`	The status of this object's external ID.Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5).
`updated_objects[].object_info.external_id`	`string`	The external ID (display ID) of this object. unset means that the external ID is the same as the internal ID.
`updated_objects[].object_info.checked_out_version`	`ObjVerVersion`	The version that is checked out. Version number 0 if the object is not checked out.
`updated_objects[].object_info.checked_out_to_user_id`	`int32`	The ID of the user who has the object checked out.
`updated_objects[].object_info.checked_out_to_user_name`	`string`	The user name of the user who has the object checked out.
`updated_objects[].object_info.checked_out_to_host_name`	`string`	The host name of the computer to which the object was checked out.
`updated_objects[].object_info.checked_out_at_utc`	`google.protobuf.Timestamp`	The timestamp of the moment the object was checked out.
`updated_objects[].object_info.checked_in_version`	`ObjVerVersion`	The latest checked-in version.
`updated_objects[].object_info.created_at_utc`	`google.protobuf.Timestamp`	The time when the object was created (same as the PROPERTYDEF_CREATED propertyvalue).
`updated_objects[].object_info.accessed_by_me_utc`	`google.protobuf.Timestamp`	Accessed by me timestamp. Parallel operations may cause slight inconsistencies in the returned timestamp in rare cases and the precise value shouldn't be relied upon. The observed timestamp may even roll back.
`updated_objects[].object_info.guid`	`string`	The object GUID, in braces. The same value as `GetObjectGUID` returns.
`updated_objects[].object_info.options`	`ITEMFLAGS`	Bit flags that provide additional information on the object (e.g. is the object deleted or a stub).
`updated_objects[].object_info.original_vault_guid`	`string`	The GUID of the vault in which the object was originally created.
`updated_objects[].object_info.original_vault_obj_id`	`ObjID`	The original objid in the vault in which the object was originally created.
`updated_objects[].object_info.associated_view_id`	`ItemID`	Identifies the view associated with this object if any.
`updated_objects[].object_info.external_repository_icon_id`	`string`	If not null, identifies the icon of the object. Currently applicable only to unmanaged objects.
`updated_objects[].object_info.primary_view_id`	`ItemID`	If not null, identifies the primary view of the object that is also the default opening location of the object. Currently applicable only to unmanaged objects.
`updated_objects[].object_info.capabilities`	`OBJECTCAPABILITYFLAGS`	Bit flags that provide information on the object capabilities.

GetLatestObjectVersion -- Gets the number and GUID of the latest version of an object.
IRPCLogin.LogIn -- Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros.
SetProperties -- Adds, replaces or removes property values of an object.
CheckOutMultiple -- Checks out several objects in one call.

IRPCObjectOperations.CheckOut

Remarks

Request: CheckOutRequest

Response: CheckOutResponse

Related methods