Vault and metadata structure

View as Markdown

An M-Files vault is not a file system. It is a database of objects (documents, customers, projects, ...) described by metadata. Folders are views computed from metadata, files belong to objects, and the meaning of every number in a request depends on which ID space it belongs to. Read this page before writing code that creates, searches or updates objects.

All calls run inside one vault: the vault is chosen at login (LoginData.vault_guid in LogIn) and the session carries it.

The building blocks

Vault
 |-- Object types and value lists   one ID space; read with GetObjectTypes / GetValueLists
 |     |-- 0 Document, 136 Customer, ...       real object types: objects with versions
 |     '-- 1 Classes, 6 Users, 154 Countries   value lists: items without versions
 |-- Classes          items of value list 1; each belongs to one object type
 |     '-- associated property definitions (required or optional), default workflow
 |-- Property definitions   0 Name or title, 100 Class, 1002 Document date, ...
 '-- Workflows (value list 7) -> states (value list 8) -> state transitions (value list 17)

Object = object type + ID; each version has a class (property 100) and property values

• Object types are the kinds of things the vault stores. Read them with GetObjectTypes. Each is a ValueList message with is_real_object_type true. options (OBJTYPEFLAGS) says, for example, whether its objects can have files (can_have_files, true for documents).
• Value lists are lists of simple items, such as Countries or Users. Read them with GetValueLists. It returns the real object types too, because object types and value lists are the same kind of thing and share one ID space: an object type is a value list whose items are full objects.
• Owners. A value list or object type can have an owner (owner_object_type): in the Sample Vault, Contact person (149) is owned by Customer (136), and Workflow States (8) are owned by Workflows (7).
• Classes subdivide an object type. Every object version has exactly one class, stored in property 100 (Class), a lookup to value list 1. Read them with GetObjectClassesAndGroups. An ObjectClass names its object_type, its associated_property_defs (each with is_required), the name_property_def that supplies the object's title, and its default_workflow (force_workflow makes it mandatory).
• Class groups (value list 2) group classes for display only. Property 101 lists them.
• Property definitions define the fields. Read them with GetPropertyDefs. A PropertyDef has a data_type (Datatype); a lookup property also has value_list, the value list or object type it points to. update_type UPDATE_TYPE_SET_BY_SERVER marks values that the server maintains and callers do not set. See Properties and values.
• Workflows and states are metadata too: an object's workflow and state are lookup properties 38 and 39. See Workflows.

The ID spaces

Most IDs in the API are plain int32 values, and the same number means different things in different spaces. Mixing them up is the most common mistake.

Two traps from the table:

• "Customer" is three different IDs. In the Sample Vault, object type Customer is 136, the class Customer is 78, and the property definition Customer (a multi-select lookup to object type 136) is 1079. A search for documents of a customer uses property 1079 with a lookup to object 141 of type 136.
• Object IDs are unique only within an object type. A search for object ID 142 without an object type returns both document 142 and customer 142. Always carry the full ObjID (type and ID).

Built-in IDs

These IDs are the same in every vault. Everything else, including every ID of 1000 or more seen in the Sample Vault, is assigned when the item is created and can differ between vaults: resolve it by alias or GUID (below) instead of hard-coding it.

Built-in classes include 0 (Document, the unclassified document), 1 (Other Document), -100 (Assignment) and -101 (Report). Built-in named ACL -1 is "Full control for all internal users"; user group 1 is "All internal users".

Aliases and GUIDs

Code that must work in more than one vault identifies structure items by alias or GUID and resolves them to IDs at run time.

• GUIDs. Every object type, property definition and value list item has a GUID (guid in ValueList, PropertyDef and ItemInfo). GetMetadataStructureItemIdByGUID resolves one: item_type METADATA_STRUCTURE_ITEM_OBJECT_TYPE with the Customer GUID returns is_found true and id 136.
• Aliases are names an administrator gives to structure items, for example MyCompany.Property.InvoiceNumber. They are stored as a semicolon-separated list in the admin structures, such as PropertyDefAdmin.aliases.
  • GetMetadataStructureItemIdByAlias resolves one alias of one MetadataStructureItem type. Matching ignores case and surrounding spaces. It returns id -1 when no item, or more than one item, has the alias; for named ACLs it returns -1000 instead, because -1 is a real named ACL.
  • GetAllMetadataStructureItemIdswithAliases returns all alias-to-ID mappings in one call (METADATA_STRUCTURE_ITEM_ALL for every type). Set unambiguous_aliases_only to true: false fails with "Not implemented."
  • The Sample Vault defines no aliases; both methods return nothing there.

Resolve aliases and GUIDs once, and cache the IDs as described in Metadata structure version and caching.

Reading the structure

Some of these responses depend on the caller: they carry the caller's permissions, for example ObjectClass.current_user_permissions.