Vault management (IRPCVaultsAdmin)

View as Markdown

Creates, attaches, detaches, destroys, upgrades, backs up, restores and copies the vaults of a server, and takes them offline and online.

Use this interface to add, modify and remove vaults. Use IRPCVaultsAdminBasic to get document vault definitions.

Overview

Server-level vault management: the vault commands of M-Files Admin and of the M-Files API's server vault management operations. Use it from administration tools and automation scripts that manage the vaults of an on-premises server. Read the definitions of existing vaults with GetVaultsAdmin and GetVaultAdmin; administer the contents of one vault with IRPCVaultAdmin.

Session and rights. Every method names its vault in the request, so a server-level session is enough: log in with login_data.vault_guid = {00000000-0000-0000-0000-000000000000}. The methods need a server right, and only logins with the system administrator server role (SRVROLES.system_administrator) have server rights:

Exceptions: UpdateVault and GetFullTextSearchInfo also accept a vault session with full control of the vault, and OptimizeVaultMetaDataDatabase a vault session with the vault right manage_scheduled_jobs. A missing server right fails with gRPC status UNKNOWN and the message "Access denied. You do not have the server-level access rights required by this operation." (error codes 0x800400A8 and 0x800407E4).

Tasks and the usual order of calls:

• Create a vault: GetDefaultDataFolderPrefix, TestConnectionToSQLDatabase (SQL Server vaults), then CreateNewVault.
• Change a vault: UpdateVault, UpgradeVault.
• Take a vault out of use: CheckForOpenSessions, TakeVaultOffline, BringVaultOnline.
• Move a vault between servers: DetachVault keeps the data; AttachExistingVault attaches it again (check first with AttachVaultToOneDbTest when the server has joined a subscription).
• Delete a vault and its data: DestroyVault.
• Back up, restore and copy: BackUpVault, GetBackupFileContents, RestoreVault, CopyVault.
• Maintenance: OptimizeVaultMetaDataDatabase, EncryptFileData, GetFullTextSearchInfo.
• Replica vaults and ground link proxies (special deployments): CreateNewReplicaVault, UpdateReplicaVault, CreateNewGroundLinkProxy, UpdateGroundLinkProxy.

Background jobs. BackUpVault, CopyVault, EncryptFileData, OptimizeVaultMetaDataDatabase, RestoreVault (unless synchronous) and, when they start a migration, UpdateVault and UpdateGroundLinkProxy create a temporary scheduled job and return its ID in task_id before the work is done. Follow the job like the M-Files API does:

1. Call GetScheduledJobRunInfo with scheduled_job = task_id about twice a second.
2. The job has finished when is_running is false and current_step is not -1 (-1 means the job has not started yet).
3. Check last_run_succeeded and last_run_errors; output holds the job's result.
4. Remove the finished job with RemoveScheduledJob. Cancel a running job with CancelScheduledJob.

These jobs are server-level jobs (except an optimization started with a vault session, which is a job of that vault). Server-level and vault-level jobs have separate IDs: read a server-level job with a server-level session, which needs the server right manage_jobs.

Methods