Items stored within an M-Files vault - aside from value lists - are considered
Objects. Each document stored to M-Files is an object. Each project - if a vault is configured to store projects - is an object. Each object is of a specific object type and ../Vault-Structure/class, and has a series of property values which together make up its metadata. Some objects contain files (e.g. documents) and some objects do not.
Whenever the metadata or files of an object are altered, M-Files automatically creates a new
Object Version. These versions can be seen by viewing the object’s history. In order to maintain this audit trail, M-Files uses a process whereby an object is checked out, altered, then checked in. Objects can only be checked out by one person at a time.
For changes that may take some time (e.g. editing a file), M-Files may prompt the user to check out the object. No other user can make alterations to this object until it is checked back in, the checkout is discarded, or an administrator overrides the checkout.
For smaller, atomic, changes, M-Files will often perform the check out and in transparently for the user. This can be seen by finding an object and altering its metadata: when clicking the
Save button, M-Files will check out the object, persist the changes, then check it back in again.
Any operation that alters the object’s metadata or files causes a new version to be created, including moving items through workflows.
The ObjID class represents a single object in the M-Files vault. The combination of the
Type (the internal ID of the object type) and the
ID (the M-Files internal ID) uniquely identify an object in the system. The
ObjID is used to reference items when the version is not important, such as for checking out an object.
The ObjVer class represents a specific version of a single object in the M-Files vault. The combination of the
Version number (always a positive integer, starting at 1), the
Type and the
ID uniquely identify a specific version of an object in the system. The
ObjVer is used to reference items when the version is important, such as loading the property values that were on a specific object version.
Object versions will be created from 1 upwards, but it is not safe to assume that all object versions are still available in the vault, nor that a specific user can necessarily see all versions. The GetHistory API method will return the items which are available for the current user.
Managing objects using the API
The following pages discuss the creation and management of objects in an M-Files vault:
- Creating objects with the COM API
- Updating objects with the COM API
- Deleting and destroying objects with the COM API