Objects and Versions

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.

Object history

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.

API objects

ObjID

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.

ObjVer

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: