Vault information (IRPCVault)
An interface for vault-level information and operations.
Provides methods for miscellaneous vault-level operations.
| gRPC service | MFiles.IRPCVault |
|---|---|
| Book and level | Vault API, core |
| Methods | 26 |
| Proto file | mfiles/IRPCVault.proto |
Overview
Vault-level lookups that most applications need right after login: the vault's own identity, turning stable identifiers (GUIDs and aliases) into the vault's numeric IDs, listing users and user groups, and detecting changes to the metadata structure.
All methods need a vault session (LogIn with a vault GUID); a server-level session fails with
E_MFILES_LOGIN_REQUIRED.
| Job | Methods |
|---|---|
| Which vault am I in? | GetVault |
| Resolve a GUID to an ID | GetMetadataStructureItemIdByGUID |
| Resolve an alias to an ID | GetMetadataStructureItemIdByAlias, GetAllMetadataStructureItemIdswithAliases, GetMetadataStructureItemIdsByAliases |
| List users and groups | GetUsersAndUserContainers, GetUsersAndUserGroupsList, GetUsersAndUserGroups |
| Groups of a user | GetGroupsOfUserOrGroup |
| Has the structure changed? | GetMetadataStructureVersion |
IDs are per vault. Object types, property definitions, classes, workflows, states and other structure items get their numeric IDs from the vault, so the same item can have different IDs in different vaults. Resolve them at run time from a GUID or an alias (set by the vault administrator) instead of hard-coding IDs, and cache the result together with the metadata structure version.
Caching. Most methods return the vault's metadata structure version in the
mfiles-metadata-version-bin trailer (4 bytes, a little-endian int32). When the number changes,
cached structure lookups are stale. Call
GetMetadataStructureVersion to check it
without other work. See
Metadata structure version and caching
and, for aliases and GUIDs,
Vault and metadata structure.
JSON in bytes fields. GetUsersAndUserGroups, the ...OrDelta methods and
GetMetadataStructureItemIdsByAliases* return JSON text in bytes fields, zlib-compressed unless
the matching length field is 4294967295. Prefer the typed alternatives named in each method.
Server push (SendPushDataResponse, SendPushDataPendingHeartbeat, NotifyDataPushEvent) and
multi-server methods (GetVaultServerAttachments, GetServerRoles, BroadcastRequest) are for
M-Files' own clients and servers.
Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| GetVault | Gets the GUID, display name and other basic data of the session's vault. | read session or assertion idempotent returns metadata structure version |
| GetMetadataStructureItemIdByAlias | Finds the vault-specific ID of a metadata structure item from one of its aliases. | read session or assertion idempotent returns metadata structure version |
| GetMetadataStructureItemIdsByAliases | Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as JSON. | write session or assertion returns metadata structure version |
| GetMetadataStructureItemIdByGUID | Finds the vault-specific ID of a metadata structure item (object type, property definition, class, workflow, ...) from its GUID. | read session or assertion idempotent returns metadata structure version |
| GetUsersAndUserGroups | Gets all users and normal user groups of the vault as JSON. | read session or assertion idempotent returns metadata structure version |
| GetMetadataStructureVersion | Gets the version numbers of the vault's metadata structure and of its property definitions. | read session or assertion idempotent |
Other methods
| Method | Summary | Facts |
|---|---|---|
| BroadcastRequest | Broadcasts a vault level request. | write session idempotent returns metadata structure version |
| GetAllMetadataStructureItemIdswithAliases | Gets all unambiguous alias-to-ID mappings of one kind of metadata structure item, or of all kinds, as typed lists. | read session or assertion idempotent returns metadata structure version |
| GetAllTranslations | Gets all translations of the vault's metadata structure names as one JSON document. | write session or assertion returns metadata structure version |
| GetGroupsOfUserOrGroup | Gets the user groups that a user or a user group belongs to. | read session or assertion idempotent returns metadata structure version |
| GetMetadataStructure | Gets the vault's real object types (not value lists), with icons, in one call. | read session or assertion idempotent returns metadata structure version |
| GetMetadataStructureItemIdsByAliases_Compressed | Gets alias-to-ID mappings of several kinds of metadata structure item as JSON, with the option to exclude kinds. | read session or assertion idempotent returns metadata structure version |
| GetMetadataStructureItemIdsFromMDCardConfiguration | Gets metadata structure item IDs and related aliases or GUIDs which are used in Metadata card configuration value. Created for HttpServer. | write session or assertion returns metadata structure version |
| GetReportAccessCredentials | Gets the report access credentials for this vault. The credentials are encrypted with the provided public key. | read session idempotent returns metadata structure version |
| GetServerRoles | Gets the multi-server roles this server has with the vault. | read session idempotent |
| GetUserContainers | Gets all user groups of the vault, of all group types, with their members. | write session or assertion returns metadata structure version |
| GetUserGroup | Gets one user group with its members. | write session or assertion returns metadata structure version |
| GetUserGroups | Gets the vault's normal user groups with their members. | read session or assertion idempotent returns metadata structure version |
| GetUsersAndUserContainers | Gets all users and all user groups of the vault. | read session or assertion idempotent returns metadata structure version |
| GetUsersAndUserContainersOrDelta | Gets users and user groups of all types as JSON, or only the changes since a version the caller already has. | read session or assertion idempotent returns metadata structure version |
| GetUsersAndUserGroupsList | Gets the names of all users and user groups in one list, with group IDs negated. | read session or assertion idempotent returns metadata structure version |
| GetUsersAndUserGroupsOrDelta | Gets users and normal user groups as JSON, or only the changes since a version the caller already has. | write session or assertion returns metadata structure version |
| GetVaultServerAttachments | Gets the servers this vault is attached to. | read session idempotent returns metadata structure version |
| NotifyDataPushEvent | Notify for server data push message change. In multi-server mode this is broadcast to all nodes and node that has client channel open can continue operation. | write session |
| SendPushDataPendingHeartbeat | Sends a heartbeat signal as an early response for server data push (with non-zero request id). | write session returns metadata structure version |
| SendPushDataResponse | Sends a response for server data push. This is a response for request received with RequestPushDataAsync call (with non-zero request id). This call completes the push data cycle. | write session returns metadata structure version |