Vault administration (IRPCVaultAdmin)
Administers the vault of the session: verify and repair, search indexes, archiving and restoring from archives, and vault-level authentication settings.
Use this interface to verify the database and perform other administrative tasks targeting the document vault.
| gRPC service | MFiles.IRPCVaultAdmin |
|---|---|
| Book and level | Administration API, specialized |
| Methods | 21 |
| Proto file | mfiles/IRPCVaultAdmin.proto |
Overview
The vault-level maintenance commands of M-Files Admin; the M-Files API's vault management operations also use VerifyVault. Use it from administration tools and automation scripts. To create, back up, take offline or destroy whole vaults, use IRPCVaultsAdmin instead.
Session and rights. Every method works on the vault of the session, so it needs a vault
session; a server-level session fails with "Login required." (error code 0x80040043). The vault
rights (fields of VaultAccess) each method needs:
| Vault right | Methods |
|---|---|
verify_vault |
VerifyVault, RebuildFullTextSearchIndexes, ExecuteIndexManagementOperation |
verify_vault |
CheckForIssue9855Errors, DismissIssue9855Errors, GetIssue9855ErrorDetails |
see_all_objects |
GetIndexOptions |
archive |
ArchiveDocuments, ArchiveOldVersions |
restore_from_archive |
RestoreFromArchive |
archive and restore_from_archive |
GetDefaultReplicationConfiguration |
change_metadata_structure and license_allows_modifications |
EnableAnnotationsAndRedlining |
| Full control of the vault | The Entra ID and authentication configuration methods |
| None | CheckAnnotationsAndRedlining |
The vault role full control (and a system administrator's full_control_of_vaults) grants all of
them. A missing right fails with gRPC status UNKNOWN, "Access denied. You do not have the access
rights required by this operation." (error codes 0x800400A9 and 0x800407E4).
Tasks:
- Check and repair the vault: VerifyVault.
- Search indexes: GetIndexOptions, ExecuteIndexManagementOperation, RebuildFullTextSearchIndexes.
- Archive and restore content:
ArchiveDocuments,
ArchiveOldVersions,
RestoreFromArchive,
GetDefaultReplicationConfiguration.
Each can first run as a preview (
preview_only) that changes nothing. - Annotations: CheckAnnotationsAndRedlining, EnableAnnotationsAndRedlining.
- Microsoft Entra ID (Azure AD) authentication: the
...AzureAD...methods, SetVaultVariables and the authentication configuration migration methods serve the vault properties of M-Files Admin. Several take binary input that only M-Files Admin produces.
Background jobs. VerifyVault (unless synchronous) and ArchiveDocuments,
ArchiveOldVersions and RestoreFromArchive (unless preview_only) create a temporary
scheduled job and return its ID in task_id before the work is done. Poll
GetScheduledJobRunInfo with
scheduled_job = task_id until is_running is false and current_step is not -1 (-1 means
not started yet), then read last_run_succeeded, last_run_errors and output. Use the right
session, because server-level and vault-level jobs have separate IDs:
- A
VerifyVaultjob is a server-level job: read it with a server-level session (log in with the null vault GUID). Reading a verification job needs no server right. - Archive and restore jobs are jobs of the vault: read them with a session of the same vault and
the vault right
archive,restore_from_archiveormanage_scheduled_jobs.
Cancel a running job with CancelScheduledJob.
Methods
| Method | Summary | Facts |
|---|---|---|
| AddAutomaticAzureADConfiguration | Creates the automatic Microsoft Entra ID (Azure AD) authentication configuration of the vault from a completed administrator consent sign-in. | internal: not for applications admin session idempotent |
| ArchiveDocuments | Exports (archives) the objects that match a filter into an archive package, or previews how many would be archived. | admin session |
| ArchiveOldVersions | Archives old versions of documents that meet the job's conditions into an archive file on the server, or previews how many would be archived. | admin session |
| CheckAnnotationsAndRedlining | Checks whether the vault has the metadata structure that the annotations and redlining feature needs. | admin session idempotent |
| CheckForIssue9855Errors | Gets the number of objects affected by a known file data problem of earlier M-Files versions that the server has detected in the vault, and that the administrator has not dismissed. | admin session idempotent |
| ContainsAutomaticAzureADConfiguration | Checks whether the vault has an automatically created Microsoft Entra ID (Azure AD) authentication configuration. | admin session idempotent |
| DeleteAutomaticAzureADConfiguration | Deletes the automatically created Microsoft Entra ID (Azure AD) authentication configuration of the vault. | admin session idempotent |
| DismissIssue9855Errors | Marks the recorded file data problems of earlier M-Files versions as dismissed. | admin session |
| EnableAnnotationsAndRedlining | Enables annotations and redlining in the vault by creating the metadata structure elements that the feature needs. | admin session idempotent |
| ExecuteIndexManagementOperation | Runs a management operation on one search index of the vault: rebuild, re-index, activate, enable, disable or delete. | admin session |
| GetAzureADProvisioningState | Gets whether user provisioning (SCIM) from Microsoft Entra ID (Azure AD) is enabled in the vault, and the license type of provisioned users. | admin session idempotent |
| GetDefaultReplicationConfiguration | Gets the default cloud storage connection string for the vault's archive and replication jobs. | admin session idempotent |
| GetIndexOptions | Lists the search indexes of the vault with their state and the management operations the caller may run on each. | admin session idempotent |
| GetIssue9855ErrorDetails | Describes the recorded file data problems of earlier M-Files versions in the vault. | admin session idempotent |
| GetMigrantAuthenticationConfigurations | Lists the authentication configurations of the vault that need to be migrated to the current format. | admin session |
| MigrateAuthenticationConfiguration | Migrates one authentication configuration of the vault to the current format after a successful test sign-in with it. | internal: not for applications admin session |
| RebuildFullTextSearchIndexes | Rebuilds the full-text search indexes of the vault: the metadata index, the file data index or both. | admin session idempotent |
| RestoreFromArchive | Imports the contents of an archive (or one object of it) into the vault, or previews the import. | admin session |
| SetAzureADProvisioningState | Enables or disables user provisioning (SCIM) from Microsoft Entra ID (Azure AD) in the vault. | admin session idempotent |
| SetVaultVariables | Sets the Microsoft Entra ID (Azure AD) consent mode of the vault. | internal: not for applications admin session idempotent |
| VerifyVault | Verifies the consistency of a vault's database and optionally of its file data, and optionally fixes the problems it finds (M-Files Admin's "Verify and Repair"). | admin session |