# M-Files gRPC API: Administration API

All pages of the Administration API of the M-Files gRPC API 26.11: the book page, then each service followed by its methods. Pages are separated by `---` lines.

---

# Administration API

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/admin/

Server and vault administration, metadata structure and user management.

28 services, 264 methods, grouped by importance level. Each service page lists its highlighted methods first, then all others.

<a id="specialized"></a>

## Specialized services

Administration and server-integration services.

| Service | Methods | Summary |
|---|---|---|
| [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `IRPCServerAdmin` | 21 | Server-wide administration: master database backup and restore, vault backups, server activity, gRPC endpoint certificates, notification (e-mail) settings, server users and the M-Files Manage subscription. |
| [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `IRPCVaultsAdmin` | 23 | Creates, attaches, detaches, destroys, upgrades, backs up, restores and copies the vaults of a server, and takes them offline and online. |
| [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `IRPCVaultsAdminBasic` | 7 | Lists the vaults, replica vaults and Ground Link proxy vaults of the server with their administrative details, as far as the caller is allowed to see them. |
| [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `IRPCVaultAdmin` | 21 | Administers the vault of the session: verify and repair, search indexes, archiving and restoring from archives, and vault-level authentication settings. |
| [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `IRPCLoginsAdmin` | 19 | Manages the server's login accounts: list, add, modify and remove logins, force logouts, look up Windows accounts and groups, and handle password resets. |
| [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `IRPCVaultLoginsAdmin` | 17 | Manages vault login accounts: login accounts stored in one vault, used on servers that have vault login accounts enabled, such as M-Files Cloud. |
| [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `IRPCUsersAdmin` | 11 | Adds, reads, modifies and removes the user accounts of a vault: who may use the vault, with which vault roles. |
| [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `IRPCUserGroupsAdmin` | 12 | Adds, reads, modifies and removes the user groups of a vault and their members. |
| [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `IRPCObjectTypesAdmin` | 18 | Administers object types and value lists: reads their full definitions, adds, modifies, converts and removes them, and manages value list items with administrator rights. |
| [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `IRPCPropertyDefsAdmin` | 14 | Administers property definitions and classes: reads their full definitions, adds, modifies and removes them, and starts recalculation of automatic values. |
| [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md) `IRPCDocClassGroupsAdmin` | 4 | Administers class groups: reads, adds, modifies and removes the groups that organize document classes. |
| [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md) `IRPCWorkflowsAdmin` | 5 | Administers workflows: reads their full definitions with states and transitions, and adds, modifies and removes them. |
| [Common views administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/index.md) `IRPCViewsAdmin` | 1 | Reads the common views and every user's private views of a vault, for administrators. |
| [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md) `IRPCNamedACLsAdmin` | 5 | Adds, reads, modifies and removes the named access control lists (permission templates) of a vault. |
| [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md) `IRPCLanguagesAdmin` | 5 | Adds, modifies and removes the languages of a vault, and reads and writes the translations of its metadata structure names. |
| [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md) `IRPCEventHandlersAdmin` | 4 | Reads and replaces the event handlers of a vault or of the server: VBScript code that the server runs when an event occurs. |
| [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `IRPCEventsAdmin` | 13 | Reads, exports and deletes the vault's event log, turns event logging on or off, and stores the caller's saved event log filters. |
| [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `IRPCScheduledJobsAdmin` | 10 | Lists, adds, changes, removes, starts and cancels scheduled jobs of the server or of a vault. |
| [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `IRPCBackgroundOperationsAdmin` | 9 | Monitors the vault's background work: refreshes of external object types and external locations, and the queue of asynchronous tasks. |
| [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `IRPCExportedDataSetsAdmin` | 9 | Manages the vault's exported data sets: the definitions of the vault data that M-Files Reporting Data Services exports to a reporting database. |
| [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `IRPCExternalLocationsAdmin` | 6 | Administers the vault's external sources: file folders and mail boxes from which the server imports or links content. |
| [Thumbnail administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/index.md) `IRPCThumbnailsAdmin` | 1 | Discards the thumbnail images stored in a vault. |
| [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `IRPCWebAccessAdmin` | 7 | Sets up M-Files Web in Internet Information Services (IIS) on the server computer. |
| [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md) `IRPCLicenseManagement` | 6 | Reads and sets the server's license, its usage, and whether licensed features such as OCR or M-Files Web are available. |
| [Monitoring status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/index.md) `IRPCMonitoringStatus` | 3 | Reads the vault's monitoring indicators; currently the status of the search indexes. |
| [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `IRPCDeclarativeMetadataStructure` | 8 | Reads and validates the whole metadata structure of a vault as one declarative JSON document. Preview feature, off by default. |
| [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md) `IRPCDeclarativeMetadataStructureAsProtobuf` | 4 | Reads and replaces the whole metadata structure of a vault as one typed message. Preview feature, off by default; for the declarative configuration converter. |
| [Cloud management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/index.md) `IRPCCloudManagementApiOperations` | 1 | Gets the identity of the server in M-Files Manage, for client features that call M-Files cloud services. |

---

# Server administration (IRPCServerAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/

Server-wide administration: master database backup and restore, vault backups, server activity,
gRPC endpoint certificates, notification (e-mail) settings, server users and the M-Files Manage
subscription.

Use this interface to perform administrative server-level operations
such as backing up and restoring the master database.

- **gRPC service:** `MFiles.IRPCServerAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 21
- **Proto file:** [`mfiles/IRPCServerAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCServerAdmin.proto)

<a id="overview"></a>

## Overview

This is the service behind the server-level nodes of M-Files Admin. Almost every method needs a
login with the **system administrator** server role; only a few are open to other users. An
application rarely needs it; automation scripts that back up vaults or read the server activity
can use it.

**Sessions and rights.** A server-level session is enough (log in with `login_data.vault_guid` =
`{00000000-0000-0000-0000-000000000000}`); a vault session works as well, except where a method
says it needs one. Server rights ([ServerAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAccess/index.md)) are granted only to
logins with the system administrator server role; a vault administrator does not have them. A
missing server right fails with "Access denied. You do not have the server-level access
rights required by this operation." (error codes 0x800400A8 and 0x800407E4).

- **Back up and restore**:
  [BackUp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUp/index.md) (vault or master database, runs as a job),
  [BackUpMasterDB](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/index.md),
  [RestoreMasterDB](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RestoreMasterDB/index.md).
- **Server activity** (the M-Files Admin dashboard):
  [GetServerActivityAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md),
  [ResetServerActivityBuffer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ResetServerActivityBuffer/index.md).
- **Vault database performance test** (vault session):
  [BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md),
  then
  [GetPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON/index.md)
  until done, then
  [EndPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON/index.md).
- **gRPC endpoint TLS and certificate**:
  [GetServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/index.md),
  [SetServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetServerEndpointSettings/index.md).
- **Notification e-mail settings**:
  [GetNotificationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetNotificationSettings/index.md),
  [SetNotificationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetNotificationSettings/index.md).
- **Server users** (server roles assigned to account names):
  [GetServerUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerUsers/index.md),
  [UpsertServerUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/UpsertServerUser/index.md),
  [RemoveServerUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RemoveServerUser/index.md).
- **M-Files Manage subscription**:
  [GetSubscriptionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetSubscriptionInfo/index.md),
  [JoinSubscriptionTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscriptionTest/index.md),
  [JoinSubscription](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md),
  [ConnectToCloud](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ConnectToCloud/index.md).
- **Process control**: [Shutdown](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/Shutdown/index.md).

Login accounts are managed with [IRPCLoginsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md), scheduled jobs
with [IRPCScheduledJobsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [BackUp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUp/index.md) | Starts a backup of a vault or of the master database as a server job and returns the job ID. | `admin` `session` |
| [BackUpMasterDB](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/index.md) | Backs up the server's master database to a file on the server, and returns when the backup is complete. | `admin` `session` |
| [BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md) | Starts a database performance measurement in the session's vault and returns its ID. | `admin` `session` `idempotent` |
| [ConnectToCloud](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ConnectToCloud/index.md) | Tells the server to fetch its licenses and login accounts from M-Files Manage so that it can start attaching its vaults. | `internal: not for applications` `admin` `session` |
| [EndPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON/index.md) | Stops and removes a performance measurement started with [BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md). | `admin` `session` `idempotent` |
| [GetNotificationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetNotificationSettings/index.md) | Gets the server's notification settings and mail-sending configuration (without the SMTP password). | `admin` `session` `idempotent` |
| [GetPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON/index.md) | Gets the current results of a vault database performance measurement as JSON. | `admin` `session` `idempotent` |
| [GetServerActivityAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md) | Gets recent server activity (connections, slowest calls, object changes, views, background processes) as a JSON document, for the M-Files Admin server activity dashboard. | `admin` `session` `idempotent` |
| [GetServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/index.md) | Gets the TLS setting and the certificate of the server's gRPC endpoint. | `admin` `session` |
| [GetServerUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerUsers/index.md) | Gets the server users: account names with server roles that are stored separately from login accounts. | `admin` `session` `idempotent` |
| [GetSubscriptionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetSubscriptionInfo/index.md) | Gets whether and how the server is connected to an M-Files Manage subscription. | `admin` `session` `idempotent` |
| [IsRunningOnNT4](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/IsRunningOnNT4/index.md) | Obsolete. Always returns false. | `admin` `session` |
| [JoinSubscription](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md) | Joins the server to an M-Files Manage subscription. | `admin` `session` |
| [JoinSubscriptionTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscriptionTest/index.md) | Checks whether the server could join an M-Files Manage subscription, and lists the vaults that would prevent it. | `admin` `session` `idempotent` |
| [RemoveServerUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RemoveServerUser/index.md) | Removes a server user, that is, the server roles stored for an account name. | `admin` `session` `idempotent` |
| [ResetServerActivityBuffer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ResetServerActivityBuffer/index.md) | Clears the server's in-memory activity buffer that [GetServerActivityAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md) reads. | `admin` `session` `idempotent` |
| [RestoreMasterDB](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RestoreMasterDB/index.md) | Replaces the server's master database with a master database backup file on the server. | `admin` `session` |
| [SetNotificationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetNotificationSettings/index.md) | Sets the server's notification settings: whether notifications are on, the daily digest time, and the SMTP or OAuth 2.0 mail settings used to send them. | `admin` `session` `idempotent` |
| [SetServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetServerEndpointSettings/index.md) | Changes the TLS setting and the certificate of the server's gRPC endpoint and restarts the endpoint. | `admin` `session` |
| [Shutdown](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/Shutdown/index.md) | Stops the M-Files Server process. | `admin` `session` |
| [UpsertServerUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/UpsertServerUser/index.md) | Adds a server user or changes the server roles of an existing one. | `admin` `session` `idempotent` |

---

# IRPCServerAdmin.BackUp

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUp/

Badges: `Administration API / specialized` `admin` `session`

Starts a backup of a vault or of the master database as a server job and returns the job ID.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/BackUp`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/back-up`
- **Request:** [`BackUpRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUp/index.md#request)
- **Response:** [`BackUpResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUp/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Starts a background job and returns before it completes. The ID is a scheduled job ID: follow
  it with [GetScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob/index.md), cancel it with
  [CancelScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md), and remove the
  job with [RemoveScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md) when it
  has finished (M-Files Admin does this).
- Requires the system administrator server role: server right `backup_vaults` for a vault,
  `backup_master_database` when `backupjob.vault_guid` is the null GUID.
- For a vault, the call first waits for the vault to finish any ongoing online/offline change.

<a id="request"></a>

## Request: BackUpRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `backupjob` | [`BackupJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackupJob/index.md) | What to back up and where. Set `vault_guid` to the vault, or to `{00000000-0000-0000-0000-000000000000}` for the master database. See [BackupJob](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackupJob/index.md). |
| `backupjob.vault_guid` | `string` | The GUID of the vault, or GUID_NULL if defining a backup of the master database. |
| `backupjob.type` | [`BackupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.BackupType/index.md) | Backup type (e.g. full or differential). Values: `BACKUP_TYPE_FULL` (0), `BACKUP_TYPE_DIFFERENTIAL` (1). |
| `backupjob.target_file` | `string` | Full path to the target file on server. |
| `backupjob.impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the backup target file on server. |
| `backupjob.impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `backupjob.impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `backupjob.impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `backupjob.overwrite_existing_files` | `bool` | If true, existing target files are overwritten. If false, backup fails if a target file already exists. |
| `backupjob.file_size_limit_in_mb` | `uint32` | Maximum size of one backup file in megabytes. If exceeded, backup will continue in a new sequentially numbered file. If zero, file size is unlimited and the backup will always consist of a single file only. |

<a id="response"></a>

## Response: BackUpResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the scheduled job that runs the backup. |

<a id="related"></a>

## Related methods

- [IRPCScheduledJobsAdmin.GetScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob/index.md): Gets one scheduled job and its run state.
- [IRPCScheduledJobsAdmin.CancelScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md): Asks a running scheduled job to stop.
- [IRPCScheduledJobsAdmin.RemoveScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md): Removes a scheduled job.
- [BackUpMasterDB](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/index.md): Backs up the server's master database to a file on the server, and returns when the backup is complete.

---

# IRPCServerAdmin.BackUpMasterDB

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/

Badges: `Administration API / specialized` `admin` `session`

Backs up the server's master database to a file on the server, and returns when the backup is
complete.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/BackUpMasterDB`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/back-up-master-db`
- **Request:** [`BackUpMasterDBRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/index.md#request)
- **Response:** [`BackUpMasterDBResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `backup_master_database`).
- The path is on the server computer. The file is written as the account in
  `utf8szimpersonation` (the server's own account when it is the system account).
- Runs synchronously. To run it as a cancellable job instead, use
  [BackUp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUp/index.md) with a `BackupJob` whose `vault_guid` is the null
  GUID.

<a id="request"></a>

## Request: BackUpMasterDBRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `target_file` | `string` | Full path of the backup file on the server computer. |
| `utf8szimpersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | The account used to write the backup file. See [Impersonation](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md). |
| `utf8szimpersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `utf8szimpersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `utf8szimpersonation.encrypted_password` | `bytes` | Encrypted password. |
| `overwrite_existing_files` | `bool` | True to overwrite existing files; false fails if a target file exists. |
| `file_size_limit_in_mb` | `uint32` | The maximum size of one backup file in megabytes; larger backups continue in sequentially numbered files. 0 means a single file of any size. |

<a id="response"></a>

## Response: BackUpMasterDBResponse

No fields.

<a id="related"></a>

## Related methods

- [BackUp](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUp/index.md): Starts a backup of a vault or of the master database as a server job and returns the job ID.

---

# IRPCServerAdmin.BeginPerformanceMeasurementsAsJSON

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Starts a database performance measurement in the session's vault and returns its ID.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/begin-performance-measurements-as-json`
- **Request:** [`BeginPerformanceMeasurementsAsJSONRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md#request)
- **Response:** [`BeginPerformanceMeasurementsAsJSONResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Starts a background operation and returns when it has started; poll the results with
  [GetPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON/index.md)
  and stop it with
  [EndPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON/index.md).
- Requires a vault session with the vault right `change_full_control_role` (vault administrators
  have it). A server-level session fails with "Login required.".
- The measurement belongs to the session: starting a new one removes any earlier measurement of
  the same session.

<a id="request"></a>

## Request: BeginPerformanceMeasurementsAsJSONRequest

No fields.

<a id="response"></a>

## Response: BeginPerformanceMeasurementsAsJSONResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `background_op_id` | `int32` | The ID of the measurement, for the Get and End calls. |

<a id="related"></a>

## Related methods

- [GetPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON/index.md): Gets the current results of a vault database performance measurement as JSON.
- [EndPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON/index.md): Stops and removes a performance measurement started with [BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md).

---

# IRPCServerAdmin.ConnectToCloud

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ConnectToCloud/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session`

Tells the server to fetch its licenses and login accounts from M-Files Manage so that it can
start attaching its vaults.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/ConnectToCloud`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/connect-to-cloud`
- **Request:** [`ConnectToCloudRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ConnectToCloud/index.md#request)
- **Response:** [`ConnectToCloudResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ConnectToCloud/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** Used for servers that run in M-Files Cloud containers.
Applications should not call it.
- Requires the system administrator server role (server rights `edit_server_properties`,
  `manage_logins` and `shutdown`).

<a id="request"></a>

## Request: ConnectToCloudRequest

No fields.

<a id="response"></a>

## Response: ConnectToCloudResponse

No fields.

---

# IRPCServerAdmin.EndPerformanceMeasurementsAsJSON

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Stops and removes a performance measurement started with
[BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md).

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/end-performance-measurements-as-json`
- **Request:** [`EndPerformanceMeasurementsAsJSONRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON/index.md#request)
- **Response:** [`EndPerformanceMeasurementsAsJSONResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/EndPerformanceMeasurementsAsJSON/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with the vault right `change_full_control_role`, in the session that
  started the measurement.

<a id="request"></a>

## Request: EndPerformanceMeasurementsAsJSONRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `background_op_id` | `int32` | The ID returned by [BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md). |

<a id="response"></a>

## Response: EndPerformanceMeasurementsAsJSONResponse

No fields.

<a id="related"></a>

## Related methods

- [BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md): Starts a database performance measurement in the session's vault and returns its ID.

---

# IRPCServerAdmin.GetNotificationSettings

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetNotificationSettings/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the server's notification settings and mail-sending configuration (without the SMTP
password).

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/GetNotificationSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-notification-settings`
- **Request:** [`GetNotificationSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetNotificationSettings/index.md#request)
- **Response:** [`GetNotificationSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetNotificationSettings/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `edit_server_properties`).
  Denied for other callers.
- `oauth2_settings` is set only when OAuth 2.0 settings are stored.

<a id="request"></a>

## Request: GetNotificationSettingsRequest

No fields.

<a id="response"></a>

## Response: GetNotificationSettingsResponse

A structure that specifies the response type for the GetNotificationSettings method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `notifications_enabled` | `bool` | Tells if the notifications are enabled. |
| `digest_notification_message_hour_utc` | `uint32` | The hour (UTC, 0-23) when the daily digest messages are sent. |
| `digest_notification_message_minute_utc` | `uint32` | The minute (0-59) when the daily digest messages are sent. |
| `smtp_server` | `string` | The SMTP server for delivering notifications. Can be an IP address or a DNS name. |
| `smtp_connection_parameters` | [`SMTPConnectionParameters`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SMTPConnectionParameters/index.md) | Parameters for SMTP connection. Values: `SMTPCONNECTION_PARAMETERS_STANDARD` (0), `SMTPCONNECTION_PARAMETERS_AUTHENTICATION_PLAIN` (1), `SMTPCONNECTION_PARAMETERS_AUTHENTICATION_LOGIN` (2), `SMTPCONNECTION_PARAMETERS_AUTHENTICATION_CRAM_MD5` (4). |
| `smtp_auth_username` | `string` | User name for SMTP authentication. |
| `smtp_mail_from_address` | `string` | The address of the sender when sending notifications. |
| `smtp_mail_from_display_name` | `string` | The display name of the sender when sending notifications. |
| `smtp_port` | `uint32` | The port the SMTP server is listening. |
| `mail_source_auth_type` | [`MailSourceAuthType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MailSourceAuthType/index.md) | The authentication method to use. Values: `MAIL_SOURCE_AUTH_TYPE_NONE` (0), `MAIL_SOURCE_AUTH_TYPE_BASIC` (1), `MAIL_SOURCE_AUTH_TYPE_OAUTH2` (2). |
| `oauth2_settings` | [`Oauth2NotificationSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Oauth2NotificationSettings/index.md) | OAuth2 specific data. |
| `oauth2_settings.mail_source` | [`MailSourceOauth2`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MailSourceOauth2/index.md) | OAuth2 specific data. |
| `oauth2_settings.mail_source.type` | [`MailSourceOauth2Type`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MailSourceOauth2Type/index.md) | OAuth2 service to use. Values: `MAIL_SOURCE_OAUTH2_TYPE_NONE` (0), `MAIL_SOURCE_OAUTH2_TYPE_MICROSOFT_OAUTH2` (1), `MAIL_SOURCE_OAUTH2_TYPE_GOOGLE_OAUTH2` (2). |
| `oauth2_settings.mail_source.status` | [`MailSourceOauth2Status`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MailSourceOauth2Status/index.md) | Authentication status. Values: `MAIL_SOURCE_OAUTH2_STATUS_NONE` (0), `MAIL_SOURCE_OAUTH2_STATUS_ERROR` (1), `MAIL_SOURCE_OAUTH2_STATUS_AUTHENTICATED` (2), `MAIL_SOURCE_OAUTH2_STATUS_EXPIRED` (3). |
| `oauth2_settings.mail_source.user_info` | `string` | Information about the authenticated user (account name etc.). |
| `oauth2_settings.mail_source.configuration` | `string` | Configuration for authentication in JSON format as name-value pairs. Use names as defined in OAuth2 standard. |
| `oauth2_settings.mail_source.token_cache` | `bytes` | Token cache. For Google OAuth2 this is in JSON format. For MSAL this is in its internal binary format. |
| `oauth2_settings.mail_source.proxy_address` | `string` | Proxy address if used. |
| `oauth2_settings.mail_from_address` | `string` | The address of the sender when sending notifications with OAuth2. |
| `oauth2_settings.authentication_timeout` | `uint32` | Maximum time in seconds to wait for the OAuth2 authentication to take place. |
| `oauth2_settings.mail_service_timeout` | `uint32` | Maximum time seconds to wait for the OAuth2 mail service request to be responded. |

---

# IRPCServerAdmin.GetPerformanceMeasurementsAsJSON

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the current results of a vault database performance measurement as JSON.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-performance-measurements-as-json`
- **Request:** [`GetPerformanceMeasurementsAsJSONRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON/index.md#request)
- **Response:** [`GetPerformanceMeasurementsAsJSONResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetPerformanceMeasurementsAsJSON/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with the vault right `change_full_control_role`. Without it the call
  fails with "Access denied." ; a server-level session fails
  with "Login required.".
- An unknown or ended measurement ID fails with "Not found.".
- The JSON format is that of M-Files Admin's vault information page and is not otherwise
  documented.

<a id="request"></a>

## Request: GetPerformanceMeasurementsAsJSONRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `background_op_id` | `int32` | The ID returned by [BeginPerformanceMeasurementsAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BeginPerformanceMeasurementsAsJSON/index.md). |

<a id="response"></a>

## Response: GetPerformanceMeasurementsAsJSONResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `results_as_json_` | `string` | The measurement results as a JSON document. |

---

# IRPCServerAdmin.GetServerActivityAsJSON

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets recent server activity (connections, slowest calls, object changes, views, background
processes) as a JSON document, for the M-Files Admin server activity dashboard.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/GetServerActivityAsJSON`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-server-activity-as-json`
- **Request:** [`GetServerActivityAsJSONRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md#request)
- **Response:** [`GetServerActivityAsJSONResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it, but the result is limited to what the caller administers:
  - a login without server rights sees only the vaults in which it has full control of the
    vault; a caller who administers no vault gets empty lists;
  - a system administrator sees all vaults and the server-level activity.
- The input and output JSON formats are those of M-Files Admin and are not otherwise documented.
  The server reads `isShowingOnlyUserActivities` (default true) from the parameters; `{}` is a
  valid parameter document.
- Reads an in-memory buffer; clear it with
  [ResetServerActivityBuffer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ResetServerActivityBuffer/index.md).

<a id="request"></a>

## Request: GetServerActivityAsJSONRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `parameters_as_json` | `string` | Query parameters as a JSON object, for example `{}`. |

<a id="response"></a>

## Response: GetServerActivityAsJSONResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `output_as_json` | `string` | The activity as a JSON object (`connections`, `functionCalls`, `objectModifications`, `views`, `backgroundProcesses`, and totals). |

<a id="related"></a>

## Related methods

- [ResetServerActivityBuffer](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ResetServerActivityBuffer/index.md): Clears the server's in-memory activity buffer that [GetServerActivityAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md) reads.

---

# IRPCServerAdmin.GetServerEndpointSettings

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/

Badges: `Administration API / specialized` `admin` `session`

Gets the TLS setting and the certificate of the server's gRPC endpoint.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/GetServerEndpointSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-server-endpoint-settings`
- **Request:** [`GetServerEndpointSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/index.md#request)
- **Response:** [`GetServerEndpointSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `shutdown`). Denied for other
  callers.
- Also fails with the same access denied error when certificate management has been disabled
  on the server.
- Fails with "Not implemented." if more than one certificate is stored.
- Only the public parts of the certificate and key are returned.

<a id="request"></a>

## Request: GetServerEndpointSettingsRequest

No fields.

<a id="response"></a>

## Response: GetServerEndpointSettingsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `server_endpoint_info` | [`ServerEndpointSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerEndpointSettings/index.md) | Whether TLS is enabled, the stored certificate, and whether changes are waiting to be applied (`has_pending_changes`). See [ServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerEndpointSettings/index.md). |
| `server_endpoint_info.use_tls` | `bool` | True to enable TLS on the endpoint. |
| `server_endpoint_info.server_certificates[]` | repeated [`ServerCertificate`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerCertificate/index.md) | Server certificates. |
| `server_endpoint_info.server_certificates[].id` | `int32` | Certificate id. |
| `server_endpoint_info.server_certificates[].certificate` | [`CertificateInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CertificateInfo/index.md) | Certificate info. |
| `server_endpoint_info.server_certificates[].private_key` | [`PrivateKeyInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PrivateKeyInfo/index.md) | Private key info. |
| `server_endpoint_info.has_pending_changes` | `bool` | True if there are pending changes on the server. |

---

# IRPCServerAdmin.GetServerUsers

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerUsers/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the server users: account names with server roles that are stored separately from login
accounts.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/GetServerUsers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-server-users`
- **Request:** [`GetServerUsersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerUsers/index.md#request)
- **Response:** [`GetServerUsersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerUsers/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it. Without the server right `manage_logins` the list is empty; the call
  does not fail.
- M-Files Admin shows these under "Server Users" on on-premises servers whose login accounts come
  from M-Files Manage.

<a id="request"></a>

## Request: GetServerUsersRequest

No fields.

<a id="response"></a>

## Response: GetServerUsersResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `serverusers[]` | repeated [`ServerUser`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerUser/index.md) | The server users, each an account name and its server roles. See [ServerUser](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerUser/index.md). |
| `serverusers[].login_name` | `string` | The login name that is associated with this server user (e.g. 'DOMAIN\user'). |
| `serverusers[].server_roles` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `serverusers[].server_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `serverusers[].server_roles.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `serverusers[].server_roles.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `serverusers[].server_roles.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |

---

# IRPCServerAdmin.GetSubscriptionInfo

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetSubscriptionInfo/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets whether and how the server is connected to an M-Files Manage subscription.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/GetSubscriptionInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-subscription-info`
- **Request:** [`GetSubscriptionInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetSubscriptionInfo/index.md#request)
- **Response:** [`GetSubscriptionInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetSubscriptionInfo/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it; no server right is needed.
- The server asks M-Files Manage for the information, so the call needs network access from the
  server; if M-Files Manage cannot be reached, a server that is not yet joined returns
  `can_join` false.

<a id="request"></a>

## Request: GetSubscriptionInfoRequest

No fields.

<a id="response"></a>

## Response: GetSubscriptionInfoResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `subscription_info` | [`SubscriptionInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SubscriptionInfo/index.md) | The subscription the server is joined to and related flags. See [SubscriptionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SubscriptionInfo/index.md). |
| `subscription_info.authentication_server` | `string` | The network address (name) of the mAuth server. |
| `subscription_info.subscription` | `string` | The subscription info server is joined to. |
| `subscription_info.manage_address` | `string` | The URL to the manage web. |
| `subscription_info.uses_one_db` | `bool` | True if server uses OneDb. |
| `subscription_info.can_join` | `bool` | True to allow changing the OneDb configuration. |
| `subscription_info.is_on_prem` | `bool` | True if joined to subscription and not in container. |
| `subscription_info.is_isolated` | `bool` | True if server is in isolated container. |

---

# IRPCServerAdmin.IsRunningOnNT4

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/IsRunningOnNT4/

Badges: `Administration API / specialized` `admin` `session`

Obsolete. Always returns false.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/IsRunningOnNT4`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/is-running-on-nt4`
- **Request:** [`IsRunningOnNT4Request`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/IsRunningOnNT4/index.md#request)
- **Response:** [`IsRunningOnNT4Response`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/IsRunningOnNT4/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `shutdown`); other callers get
  "Access denied.".

<a id="request"></a>

## Request: IsRunningOnNT4Request

No fields.

<a id="response"></a>

## Response: IsRunningOnNT4Response

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `running_on_nt4` | `bool` | Always false. |

---

# IRPCServerAdmin.JoinSubscription

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/

Badges: `Administration API / specialized` `admin` `session`

Joins the server to an M-Files Manage subscription.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/JoinSubscription`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/join-subscription`
- **Request:** [`JoinSubscriptionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md#request)
- **Response:** [`JoinSubscriptionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Changes how the server is managed. Test first with
  [JoinSubscriptionTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscriptionTest/index.md).
- Requires the system administrator server role (server rights `edit_server_properties`,
  `manage_logins` and `shutdown`).
- Fails with "Access denied." if the server already uses M-Files Manage
  (`SubscriptionInfo.uses_one_db`).

<a id="request"></a>

## Request: JoinSubscriptionRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `token` | `string` | The access token from M-Files Manage that authorizes joining. |
| `subscription_id` | `string` | The ID of the subscription to join. |

<a id="response"></a>

## Response: JoinSubscriptionResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `subscription_info` | [`SubscriptionInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SubscriptionInfo/index.md) | The subscription information after joining. |
| `subscription_info.authentication_server` | `string` | The network address (name) of the mAuth server. |
| `subscription_info.subscription` | `string` | The subscription info server is joined to. |
| `subscription_info.manage_address` | `string` | The URL to the manage web. |
| `subscription_info.uses_one_db` | `bool` | True if server uses OneDb. |
| `subscription_info.can_join` | `bool` | True to allow changing the OneDb configuration. |
| `subscription_info.is_on_prem` | `bool` | True if joined to subscription and not in container. |
| `subscription_info.is_isolated` | `bool` | True if server is in isolated container. |

<a id="related"></a>

## Related methods

- [JoinSubscriptionTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscriptionTest/index.md): Checks whether the server could join an M-Files Manage subscription, and lists the vaults that would prevent it.

---

# IRPCServerAdmin.JoinSubscriptionTest

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscriptionTest/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Checks whether the server could join an M-Files Manage subscription, and lists the vaults that
would prevent it.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/JoinSubscriptionTest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/join-subscription-test`
- **Request:** [`JoinSubscriptionTestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscriptionTest/index.md#request)
- **Response:** [`JoinSubscriptionTestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscriptionTest/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Does not join; use [JoinSubscription](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md) for that.
- Requires the system administrator server role (server rights `edit_server_properties`,
  `manage_logins` and `shutdown`).
- Fails with "Access denied." if the server already uses M-Files Manage.
- If M-Files Manage does not recognize the test request, the call succeeds with empty lists.

<a id="request"></a>

## Request: JoinSubscriptionTestRequest

A structure that specifies join subscription test request.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `token` | `string` | The access token from M-Files Manage that authorizes joining. |
| `subscription_id` | `string` | The ID of the subscription to test. |

<a id="response"></a>

## Response: JoinSubscriptionTestResponse

A structure that specifies join subscription test response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `preventing_vaults[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Array of already attached vaults. |
| `preventing_vaults[].guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `preventing_vaults[].display_name` | `string` | The vault name shown to users. |
| `preventing_vaults[].tooltip` | `string` | Optional description. Often empty. |
| `preventing_vaults[].icon` | `bytes` | The vault icon in .ico format, or empty. |
| `preventing_vaults[].dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `preventing_vaults[].dns_names.value[]` | repeated `string` | String values. |
| `foreign_vaults[]` | repeated [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Array of vaults with reserved GUID in another subscription. |
| `foreign_vaults[].guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `foreign_vaults[].display_name` | `string` | The vault name shown to users. |
| `foreign_vaults[].tooltip` | `string` | Optional description. Often empty. |
| `foreign_vaults[].icon` | `bytes` | The vault icon in .ico format, or empty. |
| `foreign_vaults[].dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `foreign_vaults[].dns_names.value[]` | repeated `string` | String values. |

<a id="related"></a>

## Related methods

- [JoinSubscription](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md): Joins the server to an M-Files Manage subscription.

---

# IRPCServerAdmin.RemoveServerUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RemoveServerUser/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Removes a server user, that is, the server roles stored for an account name.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/RemoveServerUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-server-user`
- **Request:** [`RemoveServerUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RemoveServerUser/index.md#request)
- **Response:** [`RemoveServerUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RemoveServerUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).

<a id="request"></a>

## Request: RemoveServerUserRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The `login_name` of the server user to remove. |

<a id="response"></a>

## Response: RemoveServerUserResponse

No fields.

---

# IRPCServerAdmin.ResetServerActivityBuffer

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ResetServerActivityBuffer/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Clears the server's in-memory activity buffer that
[GetServerActivityAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md) reads.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/ResetServerActivityBuffer`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-server-activity-buffer`
- **Request:** [`ResetServerActivityBufferRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ResetServerActivityBuffer/index.md#request)
- **Response:** [`ResetServerActivityBufferResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/ResetServerActivityBuffer/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Clears the activity collected so far for all vaults and all users.
- Requires the system administrator server role (server right `log_in_to_any_vault`, or
  `manage_vaults` when the license limits the administrator's rights to vaults).

<a id="request"></a>

## Request: ResetServerActivityBufferRequest

No fields.

<a id="response"></a>

## Response: ResetServerActivityBufferResponse

No fields.

<a id="related"></a>

## Related methods

- [GetServerActivityAsJSON](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerActivityAsJSON/index.md): Gets recent server activity (connections, slowest calls, object changes, views, background processes) as a JSON document, for the M-Files Admin server activity dashboard.

---

# IRPCServerAdmin.RestoreMasterDB

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RestoreMasterDB/

Badges: `Administration API / specialized` `admin` `session`

Replaces the server's master database with a master database backup file on the server.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/RestoreMasterDB`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/restore-master-db`
- **Request:** [`RestoreMasterDBRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RestoreMasterDB/index.md#request)
- **Response:** [`RestoreMasterDBResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/RestoreMasterDB/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Destructive: the current master database content is replaced by the backup.
- Requires the system administrator server role (server right `restore_master_database`).
- Fails if the file is not a master database backup.

<a id="request"></a>

## Request: RestoreMasterDBRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `source_file` | `string` | Full path of the master database backup file on the server computer. |
| `utf8szimpersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | The account used to read the backup file. See [Impersonation](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md). |
| `utf8szimpersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `utf8szimpersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `utf8szimpersonation.encrypted_password` | `bytes` | Encrypted password. |

<a id="response"></a>

## Response: RestoreMasterDBResponse

No fields.

---

# IRPCServerAdmin.SetNotificationSettings

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetNotificationSettings/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Sets the server's notification settings: whether notifications are on, the daily digest time,
and the SMTP or OAuth 2.0 mail settings used to send them.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/SetNotificationSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-notification-settings`
- **Request:** [`SetNotificationSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetNotificationSettings/index.md#request)
- **Response:** [`SetNotificationSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetNotificationSettings/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `edit_server_properties`).
- Replaces all settings; read them first with
  [GetNotificationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetNotificationSettings/index.md).
- Validation (each fails with "The parameter is incorrect." and a description): the digest hour
  must be 0-23 and the minute 0-59; with `MAIL_SOURCE_AUTH_TYPE_BASIC`, `smtp_server` and a
  non-zero `smtp_port` are required; with `MAIL_SOURCE_AUTH_TYPE_OAUTH2`, `oauth2_settings` is
  required.
- `mail_source_auth_type` `MAIL_SOURCE_AUTH_TYPE_NONE` without `oauth2_settings` is treated as
  basic SMTP authentication (for older clients); with `oauth2_settings` it fails.

<a id="request"></a>

## Request: SetNotificationSettingsRequest

A structure that specifies the request type for the SetNotificationSettings method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `notifications_enabled` | `bool` | Tells if the notifications are enabled. |
| `digest_notification_message_hour_utc` | `uint32` | The hour (UTC, 0-23) when the daily digest messages are sent. |
| `digest_notification_message_minute_utc` | `uint32` | The minute (0-59) when the daily digest messages are sent. |
| `smtp_server` | `string` | The SMTP server for delivering notifications. Can be an IP address or a DNS name. |
| `smtp_connection_parameters` | [`SMTPConnectionParameters`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SMTPConnectionParameters/index.md) | Parameters for SMTP connection. Values: `SMTPCONNECTION_PARAMETERS_STANDARD` (0), `SMTPCONNECTION_PARAMETERS_AUTHENTICATION_PLAIN` (1), `SMTPCONNECTION_PARAMETERS_AUTHENTICATION_LOGIN` (2), `SMTPCONNECTION_PARAMETERS_AUTHENTICATION_CRAM_MD5` (4). |
| `smtp_auth_username` | `string` | User name for SMTP authentication. |
| `smtp_auth_password_enc` | `string` | The SMTP password, encrypted with the server's public key ([GetPublicKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/index.md)). Append five padding characters to the password before encrypting: the server removes the last five characters after decrypting. Used only when `smtp_password_set` is true. |
| `smtp_password_set` | `bool` | True to set the SMTP password from `smtp_auth_password_enc`. |
| `smtp_mail_from_address` | `string` | The address of the sender when sending notifications. |
| `smtp_mail_from_display_name` | `string` | The display name of the sender when sending notifications. |
| `smtp_port` | `uint32` | The port the SMTP server is listening. |
| `mail_source_auth_type` | [`MailSourceAuthType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MailSourceAuthType/index.md) | `MAIL_SOURCE_AUTH_TYPE_BASIC` for SMTP or `MAIL_SOURCE_AUTH_TYPE_OAUTH2` for OAuth 2.0 (then set `oauth2_settings`). Values: `MAIL_SOURCE_AUTH_TYPE_NONE` (0), `MAIL_SOURCE_AUTH_TYPE_BASIC` (1), `MAIL_SOURCE_AUTH_TYPE_OAUTH2` (2). |
| `oauth2_settings` | [`Oauth2NotificationSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Oauth2NotificationSettings/index.md) | OAuth2 specific data. |
| `oauth2_settings.mail_source` | [`MailSourceOauth2`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MailSourceOauth2/index.md) | OAuth2 specific data. |
| `oauth2_settings.mail_source.type` | [`MailSourceOauth2Type`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MailSourceOauth2Type/index.md) | OAuth2 service to use. Values: `MAIL_SOURCE_OAUTH2_TYPE_NONE` (0), `MAIL_SOURCE_OAUTH2_TYPE_MICROSOFT_OAUTH2` (1), `MAIL_SOURCE_OAUTH2_TYPE_GOOGLE_OAUTH2` (2). |
| `oauth2_settings.mail_source.status` | [`MailSourceOauth2Status`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MailSourceOauth2Status/index.md) | Authentication status. Values: `MAIL_SOURCE_OAUTH2_STATUS_NONE` (0), `MAIL_SOURCE_OAUTH2_STATUS_ERROR` (1), `MAIL_SOURCE_OAUTH2_STATUS_AUTHENTICATED` (2), `MAIL_SOURCE_OAUTH2_STATUS_EXPIRED` (3). |
| `oauth2_settings.mail_source.user_info` | `string` | Information about the authenticated user (account name etc.). |
| `oauth2_settings.mail_source.configuration` | `string` | Configuration for authentication in JSON format as name-value pairs. Use names as defined in OAuth2 standard. |
| `oauth2_settings.mail_source.token_cache` | `bytes` | Token cache. For Google OAuth2 this is in JSON format. For MSAL this is in its internal binary format. |
| `oauth2_settings.mail_source.proxy_address` | `string` | Proxy address if used. |
| `oauth2_settings.mail_from_address` | `string` | The address of the sender when sending notifications with OAuth2. |
| `oauth2_settings.authentication_timeout` | `uint32` | Maximum time in seconds to wait for the OAuth2 authentication to take place. |
| `oauth2_settings.mail_service_timeout` | `uint32` | Maximum time seconds to wait for the OAuth2 mail service request to be responded. |

<a id="response"></a>

## Response: SetNotificationSettingsResponse

No fields.

<a id="related"></a>

## Related methods

- [GetNotificationSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetNotificationSettings/index.md): Gets the server's notification settings and mail-sending configuration (without the SMTP password).

---

# IRPCServerAdmin.SetServerEndpointSettings

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetServerEndpointSettings/

Badges: `Administration API / specialized` `admin` `session`

Changes the TLS setting and the certificate of the server's gRPC endpoint and restarts the
endpoint.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/SetServerEndpointSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-server-endpoint-settings`
- **Request:** [`SetServerEndpointSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetServerEndpointSettings/index.md#request)
- **Response:** [`SetServerEndpointSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/SetServerEndpointSettings/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `shutdown`), and certificate
  management must not be disabled on the server (see
  [GetServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/index.md)).
- Returns before the change is applied: the server applies it in the background right after the
  call and restarts the gRPC endpoint, which drops open connections. Errors in that step do not
  reach the caller; they are written to the server's event log. Read the result back with
  [GetServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/index.md).
- A new certificate must come with its private key.

<a id="request"></a>

## Request: SetServerEndpointSettingsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `value` | [`SetServerEndpointSettingsParams`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SetServerEndpointSettingsParams/index.md) | The new settings: `use_tls`, certificates to add or change, and IDs of certificates to remove. See [SetServerEndpointSettingsParams](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SetServerEndpointSettingsParams/index.md). |
| `value.use_tls` | `bool` | True to enable TLS. |
| `value.modify_or_add_certificates[]` | repeated [`ServerCertificateChangeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerCertificateChangeRequest/index.md) | Server certificates to modify or add. |
| `value.modify_or_add_certificates[].id` | `int32` | Endpoint ID to modify. -1 to create new endpoint. |
| `value.modify_or_add_certificates[].certificate_action` | [`ChangeAction`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ChangeAction/index.md) | Action to perform for the certificate. Values: `CHANGE_ACTION_UNINITIALIZED` (0), `CHANGE_ACTION_KEEP` (1), `CHANGE_ACTION_CHANGE` (2), `CHANGE_ACTION_REMOVE` (3). |
| `value.modify_or_add_certificates[].certificate` | `string` | Certificate to set, if the action is replace. |
| `value.modify_or_add_certificates[].private_key_action` | [`ChangeAction`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ChangeAction/index.md) | Action to perform for the private key. Values: `CHANGE_ACTION_UNINITIALIZED` (0), `CHANGE_ACTION_KEEP` (1), `CHANGE_ACTION_CHANGE` (2), `CHANGE_ACTION_REMOVE` (3). |
| `value.modify_or_add_certificates[].private_key` | `string` | Private key to set, if the action is replace. |
| `value.remove_certificates[]` | repeated `uint32` | Certificates to remove. |

<a id="response"></a>

## Response: SetServerEndpointSettingsResponse

No fields.

<a id="related"></a>

## Related methods

- [GetServerEndpointSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/GetServerEndpointSettings/index.md): Gets the TLS setting and the certificate of the server's gRPC endpoint.

---

# IRPCServerAdmin.Shutdown

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/Shutdown/

Badges: `Administration API / specialized` `admin` `session`

Stops the M-Files Server process.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/Shutdown`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/shutdown`
- **Request:** [`ShutdownRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/Shutdown/index.md#request)
- **Response:** [`ShutdownResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/Shutdown/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Stops the whole server: every session and every vault on it becomes unavailable until the
  service is started again. The call returns before the server has stopped.
- Requires the system administrator server role (server right `shutdown`).

<a id="request"></a>

## Request: ShutdownRequest

No fields.

<a id="response"></a>

## Response: ShutdownResponse

No fields.

---

# IRPCServerAdmin.UpsertServerUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/UpsertServerUser/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Adds a server user or changes the server roles of an existing one.

- **Service:** [Server administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/index.md) `MFiles.IRPCServerAdmin`
- **gRPC method:** `/MFiles.IRPCServerAdmin/UpsertServerUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upsert-server-user`
- **Request:** [`UpsertServerUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/UpsertServerUser/index.md#request)
- **Response:** [`UpsertServerUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/UpsertServerUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- The server user is matched by `login_name`.

<a id="request"></a>

## Request: UpsertServerUserRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `serveruser` | [`ServerUser`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerUser/index.md) | The account name and its server roles. See [ServerUser](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerUser/index.md). |
| `serveruser.login_name` | `string` | The login name that is associated with this server user (e.g. 'DOMAIN\user'). |
| `serveruser.server_roles` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `serveruser.server_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `serveruser.server_roles.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `serveruser.server_roles.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `serveruser.server_roles.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |

<a id="response"></a>

## Response: UpsertServerUserResponse

No fields.

---

# Vault management (IRPCVaultsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/

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.

- **gRPC service:** `MFiles.IRPCVaultsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 23
- **Proto file:** [`mfiles/IRPCVaultsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVaultsAdmin.proto)

<a id="overview"></a>

## 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin/index.md) and
[GetVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/index.md); administer the contents of one
vault with [IRPCVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md).

**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:

| Server right (`ServerAccess`) | Methods |
| --- | --- |
| `manage_vaults` | All methods not listed below |
| `backup_vaults` | `BackUpVault` |
| `restore_vault` | `RestoreVault`, `GetBackupFileContents` |

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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix/index.md),
  [TestConnectionToSQLDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase/index.md)
  (SQL Server vaults), then [CreateNewVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md).
- **Change a vault**: [UpdateVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md),
  [UpgradeVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpgradeVault/index.md).
- **Take a vault out of use**: [CheckForOpenSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md),
  [TakeVaultOffline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md),
  [BringVaultOnline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md).
- **Move a vault between servers**: [DetachVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md)
  keeps the data; [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md)
  attaches it again (check first with
  [AttachVaultToOneDbTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md) when the server
  has joined a subscription).
- **Delete a vault and its data**: [DestroyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DestroyVault/index.md).
- **Back up, restore and copy**: [BackUpVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BackUpVault/index.md),
  [GetBackupFileContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md),
  [RestoreVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md),
  [CopyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CopyVault/index.md).
- **Maintenance**: [OptimizeVaultMetaDataDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase/index.md),
  [EncryptFileData](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/EncryptFileData/index.md),
  [GetFullTextSearchInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo/index.md).
- **Replica vaults and ground link proxies** (special deployments):
  [CreateNewReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault/index.md),
  [UpdateReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateReplicaVault/index.md),
  [CreateNewGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy/index.md),
  [UpdateGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy/index.md).

**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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md)
   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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md). Cancel a
   running job with [CancelScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md).

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`.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md) | Attaches an existing vault (metadata database and file data files) to the server. | `admin` `session` |
| [AttachVaultToOneDbTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md) | Checks whether existing vault files can be attached on a server that has joined a subscription, without attaching them. | `admin` `session` `idempotent` |
| [BackUpVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BackUpVault/index.md) | Backs up a vault into a backup file on the server. | `admin` `session` |
| [BringVaultOnline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md) | Brings an offline vault online so that users can log in to it again. | `admin` `session` `idempotent` |
| [CheckForOpenSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md) | Checks whether users have open sessions to a vault: succeeds if there are none and fails with a list of the sessions otherwise. | `admin` `session` `idempotent` |
| [CopyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CopyVault/index.md) | Copies the specified vault into a new vault (creates the target vault). | `admin` `session` |
| [CreateNewGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy/index.md) | Creates a ground link proxy, a vault of type `VAULT_TYPE_GROUND_LINK_PROXY`. | `admin` `session` |
| [CreateNewReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault/index.md) | Creates a new replica vault. | `admin` `session` |
| [CreateNewVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md) | Creates a new document vault. | `admin` `session` |
| [DestroyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DestroyVault/index.md) | Destroys a vault: deletes its metadata database and its file data permanently and removes it from the server. | `admin` `session` |
| [DetachVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md) | Removes the vault from the server's list of registered vaults but does not remove the metadata database or file data files. | `admin` `session` |
| [EncryptFileData](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/EncryptFileData/index.md) | Encrypts the existing files of a vault with the vault's latest encryption key. | `admin` `session` |
| [GetBackupFileContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md) | Reads the vault identity and data folders stored in a backup file on the server. | `admin` `session` `idempotent` |
| [GetDefaultDataFolderPrefix](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix/index.md) | Gets the default data folder prefix of new document vaults. | `admin` `session` `idempotent` |
| [GetFullTextSearchInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo/index.md) | Gets the languages that the full-text search of a vault supports, or the server's defaults. | `admin` `session` `idempotent` |
| [OptimizeVaultMetaDataDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase/index.md) | Optimizes the metadata database of a vault. | `admin` `session` |
| [RestoreVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md) | Restores a vault from backup files on the server and attaches it. | `admin` `session` |
| [TakeVaultOffline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md) | Takes a vault offline: users cannot log in to it until it is brought online again. | `admin` `session` `idempotent` |
| [TestConnectionToSQLDatabase](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase/index.md) | Tests whether the server can connect to a Microsoft SQL Server database, for example before creating a vault in it. | `admin` `session` `idempotent` |
| [UpdateGroundLinkProxy](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy/index.md) | Updates the definition of a ground link proxy. | `admin` `session` `idempotent` |
| [UpdateReplicaVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateReplicaVault/index.md) | Updates the definition of a replica vault. | `admin` `session` `idempotent` |
| [UpdateVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md) | Changes the definition of a vault: name and other registration data, data folders, database, file data storage and vault variables. | `admin` `session` `idempotent` |
| [UpgradeVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpgradeVault/index.md) | Upgrades an old document vault to the current version. | `admin` `session` `idempotent` |

---

# IRPCVaultsAdmin.AttachExistingVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/

Badges: `Administration API / specialized` `admin` `session`

Attaches an existing vault (metadata database and file data files) to the server.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/AttachExistingVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/attach-existing-vault`
- **Request:** [`AttachExistingVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md#request)
- **Response:** [`AttachExistingVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Runs in the call: the server opens the existing database and file data, registers the vault
  and returns its definition.
- On a server that has joined a subscription, check first with
  [AttachVaultToOneDbTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md).

<a id="request"></a>

## Request: AttachExistingVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Where the vault's files are: data folders and database. If `vault.vault.guid` is the null GUID, the vault keeps the GUID stored in its files; otherwise its GUID is changed to the given one. |
| `vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vault.vault.display_name` | `string` | The vault name shown to users. |
| `vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `options` | [`AttachVaultOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AttachVaultOptions/index.md) | Options for attaching, such as which external connections to disable and whether to update the attachment GUID. |
| `options.disable` | [`ExternalConnectionOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalConnectionOptions/index.md) | Which vault's external data connection points must be put disabled? |
| `options.disable.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.disable.external_object_types` | `bool` | Connections to external objects and value list items (connections to external databases and plug-in based sources such as web services). |
| `options.disable.external_sources` | `bool` | Connections to external sources (file/e-mail). |
| `options.disable.exported_data_sets` | `bool` | Data sets for reporting and metadata export. |
| `options.disable.scheduled_export_import_jobs` | `bool` | Scheduled export and import jobs (content replication, archiving/restoring). |
| `options.disable.external_user_groups` | `bool` | Importing external users and groups e.g. from Active Directory. |
| `options.disable.event_handlers` | `bool` | Event handlers. A event handler might be a connection point to external data but not necessarily. |
| `options.disable.vault_applications` | `bool` | Vault applications. This includes connections to external repositories. |
| `options.disable.remote_indexes` | `bool` | Remote indexes. IDOL or Smart Search search engines are usually located in different servers. |
| `options.disable.anonymous_login` | `bool` | Enabling anonymous login. |
| `options.update_attachment_guid` | `bool` | Specify true if the attachment GUID should be updated. Usually, it is desirable to update the attachment GUID each time the vault is re-attached. |
| `options.fail_attach_if_bring_online_fails` | `bool` | A flag that controls if attaching the vault must fail if its online operations do not start successfully. Typically this is false meaning that starting online operations can fail although attaching the vault succeeds. |
| `options.enforce_file_data_encryption` | `bool` | A flag that controls if file data encryption should be turned on in the vault when it is attached. |
| `options.disable_local_indexes` | `bool` | A flag that controls if the local indexes such as dtSearch are disabled when the vault is attached. |
| `options.allow_only_vault_temp_path_for_content_replication` | `bool` | If true the temporary processing location of cloud replication jobs are cleared and other replication jobs are disabled. |
| `options.ignore_vault_external_data_connection_points` | `bool` | If true vault's external data connection points are ignored when vault is already in msm cluster. |
| `attach_always` | `bool` | On a server that has joined a subscription, true attaches the vault even if it is already attached to another server. |

<a id="response"></a>

## Response: AttachExistingVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `attached_vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Receives the full definition of the attached vault. |
| `attached_vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `attached_vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `attached_vault.vault.display_name` | `string` | The vault name shown to users. |
| `attached_vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `attached_vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `attached_vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `attached_vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `attached_vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `attached_vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `attached_vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `attached_vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `attached_vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `attached_vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `attached_vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `attached_vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `attached_vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `attached_vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `attached_vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `attached_vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |

<a id="related"></a>

## Related methods

- [AttachVaultToOneDbTest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md): Checks whether existing vault files can be attached on a server that has joined a subscription, without attaching them.

---

# IRPCVaultsAdmin.AttachVaultToOneDbTest

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Checks whether existing vault files can be attached on a server that has joined a subscription,
without attaching them.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/attach-vault-to-one-db-test`
- **Request:** [`AttachVaultToOneDbTestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md#request)
- **Response:** [`AttachVaultToOneDbTestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachVaultToOneDbTest/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Does not attach anything. Call it before
  [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md) on a server that has
  joined a subscription (see [JoinSubscription](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md)).
  It reads the vault files to get the vault's GUID and asks the subscription service whether the
  vault can be attached. On a server that has not joined a subscription it checks nothing and
  returns `can_be_forced` true.

<a id="request"></a>

## Request: AttachVaultToOneDbTestRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The vault files to check: data folders and database, as for [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md). |
| `vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vault.vault.display_name` | `string` | The vault name shown to users. |
| `vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `options` | [`AttachVaultOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AttachVaultOptions/index.md) | Attach options, as for AttachExistingVault. |
| `options.disable` | [`ExternalConnectionOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalConnectionOptions/index.md) | Which vault's external data connection points must be put disabled? |
| `options.disable.all` | `bool` | Specifies all flags set; Including any future flags. |
| `options.disable.external_object_types` | `bool` | Connections to external objects and value list items (connections to external databases and plug-in based sources such as web services). |
| `options.disable.external_sources` | `bool` | Connections to external sources (file/e-mail). |
| `options.disable.exported_data_sets` | `bool` | Data sets for reporting and metadata export. |
| `options.disable.scheduled_export_import_jobs` | `bool` | Scheduled export and import jobs (content replication, archiving/restoring). |
| `options.disable.external_user_groups` | `bool` | Importing external users and groups e.g. from Active Directory. |
| `options.disable.event_handlers` | `bool` | Event handlers. A event handler might be a connection point to external data but not necessarily. |
| `options.disable.vault_applications` | `bool` | Vault applications. This includes connections to external repositories. |
| `options.disable.remote_indexes` | `bool` | Remote indexes. IDOL or Smart Search search engines are usually located in different servers. |
| `options.disable.anonymous_login` | `bool` | Enabling anonymous login. |
| `options.update_attachment_guid` | `bool` | Specify true if the attachment GUID should be updated. Usually, it is desirable to update the attachment GUID each time the vault is re-attached. |
| `options.fail_attach_if_bring_online_fails` | `bool` | A flag that controls if attaching the vault must fail if its online operations do not start successfully. Typically this is false meaning that starting online operations can fail although attaching the vault succeeds. |
| `options.enforce_file_data_encryption` | `bool` | A flag that controls if file data encryption should be turned on in the vault when it is attached. |
| `options.disable_local_indexes` | `bool` | A flag that controls if the local indexes such as dtSearch are disabled when the vault is attached. |
| `options.allow_only_vault_temp_path_for_content_replication` | `bool` | If true the temporary processing location of cloud replication jobs are cleared and other replication jobs are disabled. |
| `options.ignore_vault_external_data_connection_points` | `bool` | If true vault's external data connection points are ignored when vault is already in msm cluster. |

<a id="response"></a>

## Response: AttachVaultToOneDbTestResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `can_be_forced` | `bool` | True if the subscription service allows attaching the vault (despite the name, this is the answer to the test). |
| `existing_vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | The vault that the subscription service reports for the vault's GUID, if any; otherwise its `guid` is the null GUID. |
| `existing_vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `existing_vault.display_name` | `string` | The vault name shown to users. |
| `existing_vault.tooltip` | `string` | Optional description. Often empty. |
| `existing_vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `existing_vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `existing_vault.dns_names.value[]` | repeated `string` | String values. |

<a id="related"></a>

## Related methods

- [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md): Attaches an existing vault (metadata database and file data files) to the server.
- [IRPCServerAdmin.JoinSubscription](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/JoinSubscription/index.md): Joins the server to an M-Files Manage subscription.

---

# IRPCVaultsAdmin.BackUpVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BackUpVault/

Badges: `Administration API / specialized` `admin` `session`

Backs up a vault into a backup file on the server.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/BackUpVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/back-up-vault`
- **Request:** [`BackUpVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BackUpVault/index.md#request)
- **Response:** [`BackUpVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BackUpVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes**; follow it with `task_id` (see the
  service overview).
- Requires the system administrator server role (server right `backup_vaults`).
- The server writes the file: `target_file` is a path on the server machine, accessed with the
  account in `impersonation` (unset means `IMPERSONATION_TYPE_SYSTEM_ACCOUNT`). To back up the
  master database, use [BackUpMasterDB](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/index.md).

<a id="request"></a>

## Request: BackUpVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `backupjob` | [`BackupJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackupJob/index.md) | The backup to make: the vault (`vault_guid`), full or differential (`type`), the target file on the server and whether to overwrite it. |
| `backupjob.vault_guid` | `string` | The GUID of the vault, or GUID_NULL if defining a backup of the master database. |
| `backupjob.type` | [`BackupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.BackupType/index.md) | Backup type (e.g. full or differential). Values: `BACKUP_TYPE_FULL` (0), `BACKUP_TYPE_DIFFERENTIAL` (1). |
| `backupjob.target_file` | `string` | Full path to the target file on server. |
| `backupjob.impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the backup target file on server. |
| `backupjob.impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `backupjob.impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `backupjob.impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `backupjob.overwrite_existing_files` | `bool` | If true, existing target files are overwritten. If false, backup fails if a target file already exists. |
| `backupjob.file_size_limit_in_mb` | `uint32` | Maximum size of one backup file in megabytes. If exceeded, backup will continue in a new sequentially numbered file. If zero, file size is unlimited and the backup will always consist of a single file only. |

<a id="response"></a>

## Response: BackUpVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the server-level scheduled job that makes the backup. Pass it to [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md). |

<a id="related"></a>

## Related methods

- [IRPCServerAdmin.BackUpMasterDB](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCServerAdmin/BackUpMasterDB/index.md): Backs up the server's master database to a file on the server, and returns when the backup is complete.

---

# IRPCVaultsAdmin.BringVaultOnline

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Brings an offline vault online so that users can log in to it again.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/BringVaultOnline`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/bring-vault-online`
- **Request:** [`BringVaultOnlineRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md#request)
- **Response:** [`BringVaultOnlineResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

Requires the system administrator server role (server right `manage_vaults`).

<a id="request"></a>

## Request: BringVaultOnlineRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | `string` | The GUID of the vault. |

<a id="response"></a>

## Response: BringVaultOnlineResponse

No fields.

---

# IRPCVaultsAdmin.CheckForOpenSessions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Checks whether users have open sessions to a vault: succeeds if there are none and fails with a
list of the sessions otherwise.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/CheckForOpenSessions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-for-open-sessions`
- **Request:** [`CheckForOpenSessionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md#request)
- **Response:** [`CheckForOpenSessionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Read-only. Call it before [TakeVaultOffline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md)
  with `disconnect_users` false, which fails with the same error.
- The error message lists the first 10 open sessions, one per line. Sessions of the server's own
  components and of vault applications are not counted.

<a id="request"></a>

## Request: CheckForOpenSessionsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | `string` | The GUID of the vault. |

<a id="response"></a>

## Response: CheckForOpenSessionsResponse

No fields.

<a id="related"></a>

## Related methods

- [TakeVaultOffline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md): Takes a vault offline: users cannot log in to it until it is brought online again.

---

# IRPCVaultsAdmin.CopyVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CopyVault/

Badges: `Administration API / specialized` `admin` `session`

Copies the specified vault into a new vault (creates the target vault).

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/CopyVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/copy-vault`
- **Request:** [`CopyVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CopyVault/index.md#request)
- **Response:** [`CopyVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CopyVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes**; follow it with `task_id` (see the
  service overview).
- Requires the system administrator server role (server right `manage_vaults`).
- `copy_job.options` selects what is copied; `all_data` copies everything.

<a id="request"></a>

## Request: CopyVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `copy_job` | [`CopyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CopyVaultJob/index.md) | The vault to copy (`source_vault`), what to copy (`options`) and the definition of the new vault (`target_vault`). |
| `copy_job.source_vault` | `string` | The GUID of the vault to copy. |
| `copy_job.options` | [`COPYFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.COPYFLAGS/index.md) | Flags that tell which data parts should be copied. |
| `copy_job.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `copy_job.options.all_data` | `bool` | Copy all data. All other flags are ignored. |
| `copy_job.options.value_lists` | `bool` | Copy value list definitions. |
| `copy_job.options.property_definitions` | `bool` | Copy property definitions. |
| `copy_job.options.object_classes` | `bool` | Copy classes and class groups. |
| `copy_job.options.user_accounts` | `bool` | Copy users and user groups. |
| `copy_job.options.views` | `bool` | Copy views. |
| `copy_job.options.objects` | `bool` | Copy documents and other objects (metadata). |
| `copy_job.options.value_list_items` | `bool` | Copy value list contents. |
| `copy_job.options.workflows` | `bool` | Copy workflows. |
| `copy_job.options.external_locations` | `bool` | Copy connections to external locations. |
| `copy_job.options.event_log` | `bool` | Copy event log. |
| `copy_job.options.event_handlers` | `bool` | Copy internal event handlers. |
| `copy_job.options.translations` | `bool` | Copy languages and translations. |
| `copy_job.options.exported_data_sets` | `bool` | Copy exported data sets. |
| `copy_job.options.scheduled_export_import_jobs` | `bool` | Copy scheduled export and import jobs. |
| `copy_job.options.applications` | `bool` | Copy applications. |
| `copy_job.options.files` | `bool` | Copy files. |
| `copy_job.options.use_provided_vault_guid` | `bool` | Use the provided target vault GUID. |
| `copy_job.target_vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The definition of the target vault. The GUID field is ignored. The server will generate a new GUID for the new vault. |
| `copy_job.target_vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `copy_job.target_vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `copy_job.target_vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `copy_job.target_vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `copy_job.target_vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `copy_job.target_vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `copy_job.attach_vault_options` | [`AttachVaultOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AttachVaultOptions/index.md) | Options for controlling the attaching of the vault. |
| `copy_job.attach_vault_options.disable` | [`ExternalConnectionOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalConnectionOptions/index.md) | Which vault's external data connection points must be put disabled? |
| `copy_job.attach_vault_options.update_attachment_guid` | `bool` | Specify true if the attachment GUID should be updated. Usually, it is desirable to update the attachment GUID each time the vault is re-attached. |
| `copy_job.attach_vault_options.fail_attach_if_bring_online_fails` | `bool` | A flag that controls if attaching the vault must fail if its online operations do not start successfully. Typically this is false meaning that starting online operations can fail although attaching the vault succeeds. |
| `copy_job.attach_vault_options.enforce_file_data_encryption` | `bool` | A flag that controls if file data encryption should be turned on in the vault when it is attached. |
| `copy_job.attach_vault_options.disable_local_indexes` | `bool` | A flag that controls if the local indexes such as dtSearch are disabled when the vault is attached. |
| `copy_job.attach_vault_options.allow_only_vault_temp_path_for_content_replication` | `bool` | If true the temporary processing location of cloud replication jobs are cleared and other replication jobs are disabled. |
| `copy_job.attach_vault_options.ignore_vault_external_data_connection_points` | `bool` | If true vault's external data connection points are ignored when vault is already in msm cluster. |

<a id="response"></a>

## Response: CopyVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the server-level scheduled job that copies the vault. |

---

# IRPCVaultsAdmin.CreateNewGroundLinkProxy

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy/

Badges: `Administration API / specialized` `admin` `session`

Creates a ground link proxy, a vault of type `VAULT_TYPE_GROUND_LINK_PROXY`.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-new-ground-link-proxy`
- **Request:** [`CreateNewGroundLinkProxyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy/index.md#request)
- **Response:** [`CreateNewGroundLinkProxyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewGroundLinkProxy/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Fails with an invalid-argument error unless `vault.vault_type` is
  `VAULT_TYPE_GROUND_LINK_PROXY`.

<a id="request"></a>

## Request: CreateNewGroundLinkProxyRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The definition of the new ground link proxy. |
| `vault.vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vault.vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault.vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vault.master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vault.master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vault.master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vault.master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |

<a id="response"></a>

## Response: CreateNewGroundLinkProxyResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `new_vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Receives the full definition of the new vault. |
| `new_vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `new_vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `new_vault.vault.display_name` | `string` | The vault name shown to users. |
| `new_vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `new_vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `new_vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `new_vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `new_vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `new_vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `new_vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `new_vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `new_vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `new_vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `new_vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `new_vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `new_vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `new_vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `new_vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `new_vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |

---

# IRPCVaultsAdmin.CreateNewReplicaVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault/

Badges: `Administration API / specialized` `admin` `session`

Creates a new replica vault.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-new-replica-vault`
- **Request:** [`CreateNewReplicaVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault/index.md#request)
- **Response:** [`CreateNewReplicaVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewReplicaVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Fails unless the server is configured to allow replica vaults (it fails with an error saying
  that configuring replica vaults is not allowed), and with an invalid-argument error unless
  `vault.vault_type` is `VAULT_TYPE_REPLICA_VAULT`.

<a id="request"></a>

## Request: CreateNewReplicaVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The definition of the new replica vault. |
| `vault.vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vault.vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault.vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vault.master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vault.master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vault.master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vault.master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |

<a id="response"></a>

## Response: CreateNewReplicaVaultResponse

No fields.

---

# IRPCVaultsAdmin.CreateNewVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/

Badges: `Administration API / specialized` `admin` `session`

Creates a new document vault.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/CreateNewVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-new-vault`
- **Request:** [`CreateNewVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md#request)
- **Response:** [`CreateNewVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Runs in the call and returns the new vault, with the GUID that the server generated.
- The definition is validated in full before anything is created.

<a id="request"></a>

## Request: CreateNewVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The definition of the new vault: name (`vault.vault.display_name`), data folder (`vault.main_data_folder`), database (`vault.database_info`) and file data storage. `vault.vault.guid` is ignored: the server generates a new GUID. |
| `vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vault.vault.display_name` | `string` | The vault name shown to users. |
| `vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault_variables[]` | repeated [`VaultVariable`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariable/index.md) | Vault variables to set in the new vault. |
| `vault_variables[].name` | `string` | The name of the vault variable. |
| `vault_variables[].value` | `bytes` | The value of the variable in a serialized format. |

<a id="response"></a>

## Response: CreateNewVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `new_vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The full definition of the new vault, including its new GUID. |
| `new_vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `new_vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `new_vault.vault.display_name` | `string` | The vault name shown to users. |
| `new_vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `new_vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `new_vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `new_vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `new_vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `new_vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `new_vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `new_vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `new_vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `new_vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `new_vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `new_vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `new_vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `new_vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `new_vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `new_vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |

---

# IRPCVaultsAdmin.DestroyVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DestroyVault/

Badges: `Administration API / specialized` `admin` `session`

Destroys a vault: deletes its metadata database and its file data permanently and removes it from
the server.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/DestroyVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/destroy-vault`
- **Request:** [`DestroyVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DestroyVault/index.md#request)
- **Response:** [`DestroyVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DestroyVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Destroys the vault and its data permanently.** Use
  [DetachVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md) to remove the vault from the server
  and keep the data.
- Requires the system administrator server role (server right `manage_vaults`).
- The vault is taken offline first: open sessions to the vault are disconnected.
- With `force` false, the call fails if the server cannot connect to the vault's SQL Server; with
  `force` true the vault is destroyed anyway and its database may be left on that SQL Server.

<a id="request"></a>

## Request: DestroyVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | `string` | The GUID of the vault to destroy, in braces, e.g. `{7BBEA0BC-40D8-4BCB-A67D-8A3ACFBDB575}`. |
| `force` | `bool` | True to destroy the vault even if the server cannot connect to the vault's database server; the database may then be left on that server. False to fail in that case. |

<a id="response"></a>

## Response: DestroyVaultResponse

No fields.

<a id="related"></a>

## Related methods

- [DetachVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md): Removes the vault from the server's list of registered vaults but does not remove the metadata database or file data files.

---

# IRPCVaultsAdmin.DetachVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/

Badges: `Administration API / specialized` `admin` `session`

Removes the vault from the server's list of registered vaults but does not
remove the metadata database or file data files.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/DetachVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/detach-vault`
- **Request:** [`DetachVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md#request)
- **Response:** [`DetachVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/DetachVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Takes the vault offline first: open sessions to the vault are disconnected. The metadata
  database and the file data stay, and
  [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md) can attach them again,
  on this or another server.

<a id="request"></a>

## Request: DetachVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | `string` | The GUID of the vault to detach. |

<a id="response"></a>

## Response: DetachVaultResponse

No fields.

<a id="related"></a>

## Related methods

- [AttachExistingVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/AttachExistingVault/index.md): Attaches an existing vault (metadata database and file data files) to the server.

---

# IRPCVaultsAdmin.EncryptFileData

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/EncryptFileData/

Badges: `Administration API / specialized` `admin` `session`

Encrypts the existing files of a vault with the vault's latest encryption key.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/EncryptFileData`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/encrypt-file-data`
- **Request:** [`EncryptFileDataRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/EncryptFileData/index.md#request)
- **Response:** [`EncryptFileDataResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/EncryptFileData/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes**; follow it with `task_id` (see the
  service overview).
- Requires the system administrator server role (server right `manage_vaults`).

<a id="request"></a>

## Request: EncryptFileDataRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `encryptfiledatajob` | [`EncryptFileDataJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EncryptFileDataJob/index.md) | The job. Set `vault_guid` to the GUID of the vault. |
| `encryptfiledatajob.vault_guid` | `string` | The GUID of the vault. |

<a id="response"></a>

## Response: EncryptFileDataResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the server-level scheduled job that encrypts the files. Pass it to [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md). |

---

# IRPCVaultsAdmin.GetBackupFileContents

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Reads the vault identity and data folders stored in a backup file on the server.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/GetBackupFileContents`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-backup-file-contents`
- **Request:** [`GetBackupFileContentsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md#request)
- **Response:** [`GetBackupFileContentsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `restore_vault`).
- Read-only. Use it before [RestoreVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md) to show
  which vault a backup holds and where its data was.

<a id="request"></a>

## Request: GetBackupFileContentsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `backup_file_full` | `string` | The full backup file, as a path on the server machine. |
| `backup_file_differential` | `string` | An optional differential backup file to apply on top of the full backup, as a path on the server machine. Leave empty if none. |
| `utf8szimpersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | The account the server uses to read the backup files. Unset means `IMPERSONATION_TYPE_SYSTEM_ACCOUNT`. |
| `utf8szimpersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `utf8szimpersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `utf8szimpersonation.encrypted_password` | `bytes` | Encrypted password. |

<a id="response"></a>

## Response: GetBackupFileContentsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `master_db` | `bool` | True if the file is a backup of the master database, not of a vault. |
| `display_name` | `string` | Receives the display name of the vault. |
| `vault` | `string` | Receives the unique ID of the vault. |
| `data_folder` | `string` | Receives the data folder of the vault. |
| `file_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | Receives the additional file data folders. |
| `file_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `file_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `file_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `file_data_folders[].impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `file_data_folders[].impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `file_data_folders[].impersonation.encrypted_password` | `bytes` | Encrypted password. |

<a id="related"></a>

## Related methods

- [RestoreVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md): Restores a vault from backup files on the server and attaches it.

---

# IRPCVaultsAdmin.GetDefaultDataFolderPrefix

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the default data folder prefix of new document vaults.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-default-data-folder-prefix`
- **Request:** [`GetDefaultDataFolderPrefixRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix/index.md#request)
- **Response:** [`GetDefaultDataFolderPrefixResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetDefaultDataFolderPrefix/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`); a vault
  administrator gets "Access denied".
- Read-only. M-Files Admin uses the folder as the starting value of `Vault.main_data_folder` for
  a new vault (see [CreateNewVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md)).

<a id="request"></a>

## Request: GetDefaultDataFolderPrefixRequest

No fields.

<a id="response"></a>

## Response: GetDefaultDataFolderPrefixResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `folder` | `string` | The default parent folder of the data folders of new vaults on the server, e.g. `C:\Program Files\M-Files\Server Vaults\`. Always ends with a backslash. |

<a id="related"></a>

## Related methods

- [CreateNewVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CreateNewVault/index.md): Creates a new document vault.

---

# IRPCVaultsAdmin.GetFullTextSearchInfo

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the languages that the full-text search of a vault supports, or the server's defaults.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-full-text-search-info`
- **Request:** [`GetFullTextSearchInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo/index.md#request)
- **Response:** [`GetFullTextSearchInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetFullTextSearchInfo/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires either the system administrator server role (server right `manage_vaults`) or a vault
  session with full control of the vault (a vault administrator succeeds, a normal user
  gets "Access denied").
- Read-only.

<a id="request"></a>

## Request: GetFullTextSearchInfoRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | `string` | The GUID of the vault. The null GUID `{00000000-0000-0000-0000-000000000000}` returns the server's default values instead of the values of a vault. |

<a id="response"></a>

## Response: GetFullTextSearchInfoResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `pftsinfo` | [`FullTextSearchInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FullTextSearchInfo/index.md) | The full-text search capabilities: `supported_languages` lists the languages of the language analyzers as three-letter codes, e.g. `eng`, `fin`, `ger`. |
| `pftsinfo.supported_languages[]` | repeated `string` | Array of languages that language analyzers support (String). |

---

# IRPCVaultsAdmin.OptimizeVaultMetaDataDatabase

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase/

Badges: `Administration API / specialized` `admin` `session`

Optimizes the metadata database of a vault.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/optimize-vault-meta-data-database`
- **Request:** [`OptimizeVaultMetaDataDatabaseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase/index.md#request)
- **Response:** [`OptimizeVaultMetaDataDatabaseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/OptimizeVaultMetaDataDatabase/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes**; follow it with `task_id` (see the
  service overview). A thorough optimization (`flags.is_thorough`) takes the vault offline while
  it runs; a quick one does not.
- With a server-level session, requires the system administrator server role (server right
  `manage_vaults`) and creates a server-level job.
- With a vault session, requires the vault right `manage_scheduled_jobs` and creates a job of
  that vault; follow it with a session of the same vault.

<a id="request"></a>

## Request: OptimizeVaultMetaDataDatabaseRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `optimize_vault_job` | [`OptimizeVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OptimizeVaultJob/index.md) | The optimization to run: the vault (`vault_guid`), quick or thorough (`flags.is_thorough`), whether to garbage-collect files of destroyed objects (`flags.garbage_collect_files`), and when to cancel automatically. |
| `optimize_vault_job.vault_guid` | `string` | The GUID of the vault. |
| `optimize_vault_job.flags` | [`OPTIMIZEVAULTFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OPTIMIZEVAULTFLAGS/index.md) | Flags that control the execution of this job. |
| `optimize_vault_job.flags.all` | `bool` | Specifies all flags set; Including any future flags. |
| `optimize_vault_job.flags.is_thorough` | `bool` | Thorough or quick optimization? In quick mode, only the indexes of the metadata database are refreshed. Thorough optimization performs a garbage-collection in the database and rebuilds indexes. The quick mode optimization is an online activity whereas the thorough mode optimization takes the vault offline. |
| `optimize_vault_job.flags.garbage_collect_files` | `bool` | Directs the optimization job to destroy garbage-collected data files that stand for destroyed objects. |
| `optimize_vault_job.auto_cancel_options` | [`OptimizeVaultAutoCancelOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OptimizeVaultAutoCancelOptions/index.md) | Auto-cancel options. |
| `optimize_vault_job.auto_cancel_options.auto_cancel` | `bool` | True if auto-cancel is enabled. |
| `optimize_vault_job.auto_cancel_options.auto_cancel_day` | [`Weekday`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Weekday/index.md) | Day when the job is auto-cancelled. Values: `WEEKDAY_NONE` (0), `WEEKDAY_MONDAY` (1), `WEEKDAY_TUESDAY` (2), `WEEKDAY_WEDNESDAY` (3), `WEEKDAY_THURSDAY` (4), `WEEKDAY_FRIDAY` (5), `WEEKDAY_SATURDAY` (6), `WEEKDAY_SUNDAY` (7). |
| `optimize_vault_job.auto_cancel_options.auto_cancel_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Time when the job is auto-cancelled. |
| `optimize_vault_job.auto_cancel_options.continuable` | `bool` | True if a cancelled optimization job can be continued on the next run. |

<a id="response"></a>

## Response: OptimizeVaultMetaDataDatabaseResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the scheduled job that runs the optimization. |

---

# IRPCVaultsAdmin.RestoreVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/

Badges: `Administration API / specialized` `admin` `session`

Restores a vault from backup files on the server and attaches it.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/RestoreVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/restore-vault`
- **Request:** [`RestoreVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md#request)
- **Response:** [`RestoreVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/RestoreVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Long-running.** With `synchronous` false the call starts a background job and returns before
  it completes; follow it with `task_id` (see the service overview). With `synchronous` true the
  call returns when the restore is done.
- Requires the system administrator server role (server right `restore_vault`).
- The backup files are read by the server: paths are on the server machine. Inspect a backup with
  [GetBackupFileContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md) first.
- `restore_job.overwrite_existing_files` true lets the restore overwrite existing files in the
  target location.

<a id="request"></a>

## Request: RestoreVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `restore_job` | [`RestoreJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreJob/index.md) | The backup files to restore and the definition of the restored vault. If `target_vault.vault.guid` is the null GUID, the vault keeps the GUID stored in the backup. |
| `restore_job.full_backup_file` | `string` | Full path to the backup file on server (full backup). |
| `restore_job.differential_backup_file` | `string` | Full path to the backup file on server (differential backup, optional). |
| `restore_job.target_vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The definition of the vault. If the GUID field is GUID_NULL, the restored vault uses the GUID specified in the backup files. Otherwise, it uses the given GUID (= restore to a different identity). |
| `restore_job.target_vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `restore_job.target_vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `restore_job.target_vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `restore_job.target_vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `restore_job.target_vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `restore_job.target_vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `restore_job.overwrite_existing_files` | `bool` | If true, existing target files are overwritten. If false, restore fails if a target file already exists. |
| `restore_job.impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the backup file on server. |
| `restore_job.impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `restore_job.impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `restore_job.impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `restore_job.vault_attach_options` | [`AttachVaultOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AttachVaultOptions/index.md) | Options for controlling the attaching of the vault. |
| `restore_job.vault_attach_options.disable` | [`ExternalConnectionOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalConnectionOptions/index.md) | Which vault's external data connection points must be put disabled? |
| `restore_job.vault_attach_options.update_attachment_guid` | `bool` | Specify true if the attachment GUID should be updated. Usually, it is desirable to update the attachment GUID each time the vault is re-attached. |
| `restore_job.vault_attach_options.fail_attach_if_bring_online_fails` | `bool` | A flag that controls if attaching the vault must fail if its online operations do not start successfully. Typically this is false meaning that starting online operations can fail although attaching the vault succeeds. |
| `restore_job.vault_attach_options.enforce_file_data_encryption` | `bool` | A flag that controls if file data encryption should be turned on in the vault when it is attached. |
| `restore_job.vault_attach_options.disable_local_indexes` | `bool` | A flag that controls if the local indexes such as dtSearch are disabled when the vault is attached. |
| `restore_job.vault_attach_options.allow_only_vault_temp_path_for_content_replication` | `bool` | If true the temporary processing location of cloud replication jobs are cleared and other replication jobs are disabled. |
| `restore_job.vault_attach_options.ignore_vault_external_data_connection_points` | `bool` | If true vault's external data connection points are ignored when vault is already in msm cluster. |
| `synchronous` | `bool` | True to restore within the call. False to start a background job and return at once. |

<a id="response"></a>

## Response: RestoreVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the server-level restore job when `synchronous` is false; -1 when it is true. |
| `output_info` | [`RestoreJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreJobOutputInfo/index.md) | The restored vault when `synchronous` is true; empty otherwise (read the result from the job's `output`). |
| `output_info.restored_vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Receives the full definition of the restored vault. |
| `output_info.restored_vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `output_info.restored_vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `output_info.restored_vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `output_info.restored_vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `output_info.restored_vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `output_info.restored_vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |

<a id="related"></a>

## Related methods

- [GetBackupFileContents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/GetBackupFileContents/index.md): Reads the vault identity and data folders stored in a backup file on the server.

---

# IRPCVaultsAdmin.TakeVaultOffline

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Takes a vault offline: users cannot log in to it until it is brought online again.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/TakeVaultOffline`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/take-vault-offline`
- **Request:** [`TakeVaultOfflineRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md#request)
- **Response:** [`TakeVaultOfflineResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TakeVaultOffline/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- With `disconnect_users` false, the call fails if the vault has open sessions, with the same
  error as [CheckForOpenSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md). With
  `disconnect_users` true, open sessions are terminated.
- Bring the vault back with [BringVaultOnline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md).

<a id="request"></a>

## Request: TakeVaultOfflineRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | `string` | The GUID of the vault. |
| `disconnect_users` | `bool` | If true, any existing sessions are terminated. If false, the operation fails if there are open sessions. |

<a id="response"></a>

## Response: TakeVaultOfflineResponse

No fields.

<a id="related"></a>

## Related methods

- [CheckForOpenSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/CheckForOpenSessions/index.md): Checks whether users have open sessions to a vault: succeeds if there are none and fails with a list of the sessions otherwise.
- [BringVaultOnline](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/BringVaultOnline/index.md): Brings an offline vault online so that users can log in to it again.

---

# IRPCVaultsAdmin.TestConnectionToSQLDatabase

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Tests whether the server can connect to a Microsoft SQL Server database, for example before
creating a vault in it.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/test-connection-to-sqldatabase`
- **Request:** [`TestConnectionToSQLDatabaseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase/index.md#request)
- **Response:** [`TestConnectionToSQLDatabaseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/TestConnectionToSQLDatabase/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Succeeds with an empty response if the connection works; fails with the connection error
  otherwise. The server tries once only, so a mistyped server name fails fast.

<a id="request"></a>

## Request: TestConnectionToSQLDatabaseRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `sqldb` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The database server, database name and credentials to test. |
| `sqldb.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `sqldb.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `sqldb.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `sqldb.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `sqldb.system_admin_impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `sqldb.system_admin_impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `sqldb.system_admin_impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `sqldb.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `sqldb.basic_user_impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `sqldb.basic_user_impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `sqldb.basic_user_impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `database_should_exist` | `bool` | True to also fail if the database does not exist. False accepts both an existing and a missing database (a new vault can use an existing empty database). |

<a id="response"></a>

## Response: TestConnectionToSQLDatabaseResponse

No fields.

---

# IRPCVaultsAdmin.UpdateGroundLinkProxy

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Updates the definition of a ground link proxy.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-ground-link-proxy`
- **Request:** [`UpdateGroundLinkProxyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy/index.md#request)
- **Response:** [`UpdateGroundLinkProxyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateGroundLinkProxy/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Changes the registration data only. If the change starts a migration, `task_id` is the ID of a
  background job (see the service overview); otherwise it is -1.

<a id="request"></a>

## Request: UpdateGroundLinkProxyRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The new definition of the ground link proxy. The vault to modify is determined from the vault GUID which cannot change. |
| `vault.vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vault.vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault.vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vault.master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vault.master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vault.master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vault.master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |

<a id="response"></a>

## Response: UpdateGroundLinkProxyResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | Receives a task identifier associated with vault migration to allow the caller to cancel the operation or/and request status information about it. If -1, no migration is performed. |

---

# IRPCVaultsAdmin.UpdateReplicaVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateReplicaVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Updates the definition of a replica vault.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/UpdateReplicaVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-replica-vault`
- **Request:** [`UpdateReplicaVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateReplicaVault/index.md#request)
- **Response:** [`UpdateReplicaVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateReplicaVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Changes the registration data of the replica vault only.

<a id="request"></a>

## Request: UpdateReplicaVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The new definition of the replica vault. The vault to modify is determined from the vault GUID which cannot change. |
| `vault.vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vault.vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault.vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vault.master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vault.master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vault.master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vault.master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |

<a id="response"></a>

## Response: UpdateReplicaVaultResponse

No fields.

---

# IRPCVaultsAdmin.UpdateVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Changes the definition of a vault: name and other registration data, data folders, database,
file data storage and vault variables.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/UpdateVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-vault`
- **Request:** [`UpdateVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md#request)
- **Response:** [`UpdateVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`), or a vault
  session with full control of the vault. Without `manage_vaults`, changing the GUID, the data
  folders, the database or the file data storage fails with "Access denied", and so does
  changing vault variables reserved for system administrators.
- The name, description, icon and vault variables change without interrupting users. Changing
  the GUID, the data folders, the database or the file data storage can take the vault offline,
  disconnecting open sessions.
- Changing the database engine (for example from Firebird to Microsoft SQL Server) or the file
  data storage of a SQL Server vault starts a background migration job: `task_id` is its ID
  (follow it as described in the service overview), or -1 if no migration started.

<a id="request"></a>

## Request: UpdateVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `guid` | `string` | The GUID of the vault to change. |
| `vault_info` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The new definition. A `vault_info.vault.guid` different from `guid` changes the vault's GUID. An empty `vault_info.database_info.database_name` leaves the database settings unchanged. |
| `vault_info.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault_info.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vault_info.vault.display_name` | `string` | The vault name shown to users. |
| `vault_info.vault.tooltip` | `string` | Optional description. Often empty. |
| `vault_info.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `vault_info.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `vault_info.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault_info.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault_info.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `vault_info.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `vault_info.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `vault_info.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault_info.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `vault_info.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `vault_info.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `vault_info.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `vault_info.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `vault_info.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault_info.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault_variables[]` | repeated [`VaultVariable`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariable/index.md) | Vault variables to set. |
| `vault_variables[].name` | `string` | The name of the vault variable. |
| `vault_variables[].value` | `bytes` | The value of the variable in a serialized format. |
| `update_only_registration_data` | `bool` | True to change only the vault's registration on the server (name, locations, database and storage settings): `vault_variables` are not applied and the definition is not validated in full. False to apply `vault_variables` too. |

<a id="response"></a>

## Response: UpdateVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the server-level migration job, or -1 if no migration started. |

---

# IRPCVaultsAdmin.UpgradeVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpgradeVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Upgrades an old document vault to the current version.

- **Service:** [Vault management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) `MFiles.IRPCVaultsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultsAdmin/UpgradeVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/upgrade-vault`
- **Request:** [`UpgradeVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpgradeVault/index.md#request)
- **Response:** [`UpgradeVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpgradeVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_vaults`).
- Runs in the call and returns when the upgrade is done. `upgraded` is false if the vault already
  had the current version.

<a id="request"></a>

## Request: UpgradeVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault` | `string` | The GUID of the vault to upgrade. |

<a id="response"></a>

## Response: UpgradeVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `upgraded` | `bool` | If true, the vault was upgraded. If false, the vault was already of the latest version. |

---

# Vault management (basic) (IRPCVaultsAdminBasic)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/

Lists the vaults, replica vaults and Ground Link proxy vaults of the server with their
administrative details, as far as the caller is allowed to see them.

Use this interface to get document vault definitions. Use IRPCVaultsAdmin to add, modify and remove vaults.
We have separated these read operations from operations that manipulate vaults to a dedicated interface to get better
isolation. These read operations do not require the "manage vaults" server-level right. So, users with full control of
vault can use these methods. These methods need to be supported even if the user does not have the "manage vaults"
server-level right so that the user could control his vaults, e.g., change various metadata elements. This is the case
in cloud vault.

- **gRPC service:** `MFiles.IRPCVaultsAdminBasic`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 7
- **Proto file:** [`mfiles/IRPCVaultsAdminBasic.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVaultsAdminBasic.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service to fill its "Document Vaults" node. Unlike the vault-changing
administration services, these read methods are open to any session: the server decides how
much to return.

**Sessions and rights.** A server-level session is enough (log in with `login_data.vault_guid` =
`{00000000-0000-0000-0000-000000000000}`); a vault session works too. No right is required, but:

- With the server right `manage_vaults` ([ServerAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAccess/index.md); system
  administrators have it), `can_manage_vaults` is true and the vault data is complete (data
  folders, database settings, file data storage), except database credentials.
- Otherwise `can_manage_vaults` is false and only the basic vault data (GUID, name, host names)
  is filled. [GetVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/index.md) adds the database
  engine and file data storage type when called in a vault session with full control of the
  vault.
- The vault lists of callers without `manage_vaults` contain only the vaults in which they have
  a user account.

Methods: [GetVaultsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin/index.md) and
[GetVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/index.md) for ordinary vaults,
[GetReplicasOfVaultsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicasOfVaultsAdmin/index.md) and
[GetReplicaOfVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicaOfVaultAdmin/index.md) for replica
vaults, [GetGroundLinkProxiesAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxiesAdmin/index.md)
and [GetGroundLinkProxyAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxyAdmin/index.md) for
Ground Link proxy vaults. [GetAddInSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetAddInSettings/index.md)
is for M-Files' own web components.

To list the vaults a user can log in to, use [IRPCVaults](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaults/index.md) instead.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [GetAddInSettings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetAddInSettings/index.md) | Gets the cross-origin (CORS) and cross-frame settings that a vault's add-in configuration allows. | `internal: not for applications` `admin` `no session` |
| [GetGroundLinkProxiesAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxiesAdmin/index.md) | Lists the Ground Link proxy vaults of the server, including offline ones. | `admin` `session` `idempotent` |
| [GetGroundLinkProxyAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxyAdmin/index.md) | Gets one Ground Link proxy vault with its administrative details. | `admin` `session` `idempotent` |
| [GetReplicaOfVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicaOfVaultAdmin/index.md) | Gets one replica vault with its administrative details. | `admin` `session` `idempotent` |
| [GetReplicasOfVaultsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicasOfVaultsAdmin/index.md) | Lists the replica vaults of the server. | `admin` `session` `idempotent` |
| [GetVaultAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/index.md) | Gets one ordinary vault with its administrative details. | `admin` `session` `idempotent` |
| [GetVaultsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin/index.md) | Lists the ordinary vaults of the server (not replicas or Ground Link proxies) with their administrative details, including offline vaults. | `admin` `session` `idempotent` |

---

# IRPCVaultsAdminBasic.GetAddInSettings

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetAddInSettings/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `no session`

Gets the cross-origin (CORS) and cross-frame settings that a vault's add-in configuration
allows.

- **Service:** [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `MFiles.IRPCVaultsAdminBasic`
- **gRPC method:** `/MFiles.IRPCVaultsAdminBasic/GetAddInSettings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-add-in-settings`
- **Request:** [`GetAddInSettingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetAddInSettings/index.md#request)
- **Response:** [`GetAddInSettingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetAddInSettings/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** M-Files' web components read it to decide which external sites
may call or frame the vaults' web endpoints. Applications should not call it.

<a id="request"></a>

## Request: GetAddInSettingsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault_guid` | `string` | The vault GUID, with braces. |

<a id="response"></a>

## Response: GetAddInSettingsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `add_in_settings_of_vaults[]` | repeated [`AddInSettingsOfVault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AddInSettingsOfVault/index.md) | The add-in settings. See [AddInSettingsOfVault](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AddInSettingsOfVault/index.md). |
| `add_in_settings_of_vaults[].vault` | `string` | The GUID of Vault. |
| `add_in_settings_of_vaults[].vault_domain_names[]` | repeated `string` | The domain names. |
| `add_in_settings_of_vaults[].settings` | [`AddInSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AddInSettings/index.md) | The settings. |
| `add_in_settings_of_vaults[].settings.allowed_methods[]` | repeated `string` | The list of allowed HTTP Methods. |
| `add_in_settings_of_vaults[].settings.allowed_cross_frame_sites[]` | repeated `string` | The list of allowed Cross Frame Sites. |
| `add_in_settings_of_vaults[].settings.allowed_headers[]` | repeated `string` | The list of allowed HTTP Response Headers. |
| `add_in_settings_of_vaults[].settings.cross_origin_access[]` | repeated `string` | The list of Cross Origin Access Domains. |
| `add_in_settings_of_vaults[].settings.allow_credentials` | `bool` | True to allow the credentials, false to skip credentials. |
| `add_in_settings_of_vaults[].settings.prevent_xfs` | `bool` | True to Prevent XFS, false to allow XFS. |

---

# IRPCVaultsAdminBasic.GetGroundLinkProxiesAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxiesAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the Ground Link proxy vaults of the server, including offline ones.

- **Service:** [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `MFiles.IRPCVaultsAdminBasic`
- **gRPC method:** `/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxiesAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-ground-link-proxies-admin`
- **Request:** [`GetGroundLinkProxiesAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxiesAdmin/index.md#request)
- **Response:** [`GetGroundLinkProxiesAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxiesAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it. With the server right `manage_vaults` the data is complete;
  otherwise only the basic data is filled.
- `vaults`, `vault_variables` and `online_states` are parallel lists.

<a id="request"></a>

## Request: GetGroundLinkProxiesAdminRequest

A structure that specifies get ground link proxies admin request.

No fields.

<a id="response"></a>

## Response: GetGroundLinkProxiesAdminResponse

A structure that specifies get ground link proxies admin response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `can_manage_vaults` | `bool` | True if the caller has the server right `manage_vaults`; then the vault data is complete. |
| `vaults[]` | repeated [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The Ground Link proxy vaults. With `can_manage_vaults` all fields are filled except database credentials; otherwise only the basic data. See [VaultEx](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md). |
| `vaults[].vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vaults[].vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vaults[].vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vaults[].vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vaults[].vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vaults[].vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vaults[].vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vaults[].vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vaults[].master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vaults[].master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vaults[].master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vaults[].master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |
| `vault_variables[]` | repeated [`VaultVariableArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariableArray/index.md) | The vault variables of each vault, in the order of `vaults`. Not valid for offline vaults. |
| `vault_variables[].value[]` | repeated [`VaultVariable`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariable/index.md) | Array of vault variables (VaultVariable). |
| `vault_variables[].value[].name` | `string` | The name of the vault variable. |
| `vault_variables[].value[].value` | `bytes` | The value of the variable in a serialized format. |
| `online_states[]` | repeated `bool` | Whether each vault is online, in the order of `vaults`. |

---

# IRPCVaultsAdminBasic.GetGroundLinkProxyAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxyAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets one Ground Link proxy vault with its administrative details.

- **Service:** [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `MFiles.IRPCVaultsAdminBasic`
- **gRPC method:** `/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxyAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-ground-link-proxy-admin`
- **Request:** [`GetGroundLinkProxyAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxyAdmin/index.md#request)
- **Response:** [`GetGroundLinkProxyAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetGroundLinkProxyAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it. With the server right `manage_vaults` the data is complete;
  otherwise only the basic data is filled.
- A GUID that is not a Ground Link proxy vault (also an ordinary vault) fails with "The specified
  document vault does not exist.".

<a id="request"></a>

## Request: GetGroundLinkProxyAdminRequest

A structure that specifies get ground link proxy admin request.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `guid` | `string` | The GUID of the Ground Link proxy vault, with braces. |

<a id="response"></a>

## Response: GetGroundLinkProxyAdminResponse

A structure that specifies get ground link proxy admin response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `can_manage_vaults` | `bool` | True if the caller has the server right `manage_vaults`. |
| `vault` | [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The vault. With `can_manage_vaults` all fields are filled except database credentials; otherwise only the basic data. See [VaultEx](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md). |
| `vault.vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vault.vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault.vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vault.master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vault.master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vault.master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vault.master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |
| `vault_variables[]` | repeated [`VaultVariable`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariable/index.md) | Always empty for Ground Link proxy vaults. |
| `vault_variables[].name` | `string` | The name of the vault variable. |
| `vault_variables[].value` | `bytes` | The value of the variable in a serialized format. |
| `online_state` | `bool` | The online state of the vault. |

---

# IRPCVaultsAdminBasic.GetReplicaOfVaultAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicaOfVaultAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets one replica vault with its administrative details.

- **Service:** [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `MFiles.IRPCVaultsAdminBasic`
- **gRPC method:** `/MFiles.IRPCVaultsAdminBasic/GetReplicaOfVaultAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-replica-of-vault-admin`
- **Request:** [`GetReplicaOfVaultAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicaOfVaultAdmin/index.md#request)
- **Response:** [`GetReplicaOfVaultAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicaOfVaultAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it. With the server right `manage_vaults` the data is complete;
  otherwise only the basic data is filled.
- A GUID of a vault that is not a replica fails with "The parameter is incorrect."; an unknown
  GUID with "The specified document vault does not exist.".

<a id="request"></a>

## Request: GetReplicaOfVaultAdminRequest

A structure that specifies get replica of vault admin request.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `guid` | `string` | The GUID of the replica vault, with braces. |

<a id="response"></a>

## Response: GetReplicaOfVaultAdminResponse

A structure that specifies get replica of vault admin response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `can_manage_vaults` | `bool` | True if the caller has the server right `manage_vaults`. |
| `vault` | [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The replica vault. With `can_manage_vaults` all fields are filled except database credentials; otherwise only the basic data. See [VaultEx](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md). |
| `vault.vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vault.vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault.vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vault.master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vault.master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vault.master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vault.master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |
| `online_state` | `bool` | The online state of the vault. |

---

# IRPCVaultsAdminBasic.GetReplicasOfVaultsAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicasOfVaultsAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the replica vaults of the server.

- **Service:** [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `MFiles.IRPCVaultsAdminBasic`
- **gRPC method:** `/MFiles.IRPCVaultsAdminBasic/GetReplicasOfVaultsAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-replicas-of-vaults-admin`
- **Request:** [`GetReplicasOfVaultsAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicasOfVaultsAdmin/index.md#request)
- **Response:** [`GetReplicasOfVaultsAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetReplicasOfVaultsAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it, and every caller sees all replica vaults. With the server right
  `manage_vaults` the data is complete; otherwise only the basic data is filled.
- `vaults` and `online_states` are parallel lists.

<a id="request"></a>

## Request: GetReplicasOfVaultsAdminRequest

A structure that specifies get replicas of vaults admin request.

No fields.

<a id="response"></a>

## Response: GetReplicasOfVaultsAdminResponse

A structure that specifies get replicas of vaults admin response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `can_manage_vaults` | `bool` | True if the caller has the server right `manage_vaults`; then the vault data is complete. |
| `vaults[]` | repeated [`VaultEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md) | The replica vaults, with `master_server_address`. With `can_manage_vaults` all fields are filled except database credentials; otherwise only the basic data. See [VaultEx](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultEx/index.md). |
| `vaults[].vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | Basic data. |
| `vaults[].vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vaults[].vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vaults[].vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vaults[].vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vaults[].vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vaults[].vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vaults[].vault_type` | [`VaultType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VaultType/index.md) | The vault type. Values: `VAULT_TYPE_NORMAL_VAULT` (0), `VAULT_TYPE_REPLICA_VAULT` (1), `VAULT_TYPE_GROUND_LINK_PROXY` (2). |
| `vaults[].master_server_address` | [`ServerAddress`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAddress/index.md) | The address of the master server. Specified if the vault type is 'replica'. |
| `vaults[].master_server_address.network_address` | `string` | The network address (name) of the server. |
| `vaults[].master_server_address.endpoint` | `string` | The endpoint of the server. |
| `vaults[].master_server_address.protocol_sequence` | `string` | The protocol sequence of the server. |
| `online_states[]` | repeated `bool` | Whether each vault is online, in the order of `vaults`. |

---

# IRPCVaultsAdminBasic.GetVaultAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets one ordinary vault with its administrative details.

- **Service:** [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `MFiles.IRPCVaultsAdminBasic`
- **gRPC method:** `/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-admin`
- **Request:** [`GetVaultAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/index.md#request)
- **Response:** [`GetVaultAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it, for any vault GUID of the server.
- The detail depends on the caller: with the server right `manage_vaults`, complete data
  except database credentials; in a vault session with full control of the session's vault, the
  basic data plus `database_info.engine` and `file_data_storage`; otherwise the
  basic data only.
- An unknown GUID fails with "The specified document vault does not exist."; a
  replica vault fails with "The parameter is incorrect.".
- Waits if the vault is being brought online or offline.

<a id="request"></a>

## Request: GetVaultAdminRequest

A structure that specifies get vault admin request.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `guid` | `string` | The vault GUID with braces. |

<a id="response"></a>

## Response: GetVaultAdminResponse

A structure that specifies get vault admin response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `can_manage_vaults` | `bool` | True if the caller has the server right `manage_vaults`. |
| `vault` | [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The vault. The fields filled depend on the caller (see the remarks). See [Vault](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md). |
| `vault.vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vault.vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vault.vault.display_name` | `string` | The vault name shown to users. |
| `vault.vault.tooltip` | `string` | Optional description. Often empty. |
| `vault.vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `vault.vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `vault.main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vault.additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vault.additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `vault.additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `vault.additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `vault.database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vault.database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `vault.database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `vault.database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `vault.database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `vault.database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `vault.file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vault.file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault_variables[]` | repeated [`VaultVariable`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariable/index.md) | The vault variables, such as the full-text search language and the ACL mode, returned to every caller. |
| `vault_variables[].name` | `string` | The name of the vault variable. |
| `vault_variables[].value` | `bytes` | The value of the variable in a serialized format. |
| `online_state` | `bool` | The online state of the vault. |
| `tenants_enabled_for_office` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | The Microsoft 365 tenant IDs where M-Files integrations have been enabled, if the server has this information; otherwise empty. |
| `tenants_enabled_for_office.value[]` | repeated `string` | String values. |

---

# IRPCVaultsAdminBasic.GetVaultsAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the ordinary vaults of the server (not replicas or Ground Link proxies) with their
administrative details, including offline vaults.

- **Service:** [Vault management (basic)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/index.md) `MFiles.IRPCVaultsAdminBasic`
- **gRPC method:** `/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vaults-admin`
- **Request:** [`GetVaultsAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin/index.md#request)
- **Response:** [`GetVaultsAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdminBasic/GetVaultsAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it.
- With the server right `manage_vaults`: all vaults, with complete data. Otherwise: only vaults in
  which the caller has a user account (enabled or disabled), with basic data only. On servers
  with vault login accounts, a caller whose login comes from a vault sees only that vault.
- `vaults`, `vault_variables` and `online_states` are parallel lists: entry *i* of each describes
  the same vault. The order is not specified.
- Waits for vaults that are being brought online or offline before returning.

<a id="request"></a>

## Request: GetVaultsAdminRequest

A structure that specifies get vaults admin request.

No fields.

<a id="response"></a>

## Response: GetVaultsAdminResponse

A structure that specifies get vaults admin response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `can_manage_vaults` | `bool` | True if the caller has the server right `manage_vaults`; then the vault data is complete. |
| `vaults[]` | repeated [`Vault`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md) | The vaults. With `can_manage_vaults` all fields are filled except database credentials; otherwise only the basic data (`vault`: GUID, name, host names). See [Vault](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Vault/index.md). |
| `vaults[].vault` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) | Basic data. |
| `vaults[].vault.guid` | `string` | The vault GUID, in braces and upper case. Use it as `LoginData.vault_guid`. |
| `vaults[].vault.display_name` | `string` | The vault name shown to users. |
| `vaults[].vault.tooltip` | `string` | Optional description. Often empty. |
| `vaults[].vault.icon` | `bytes` | The vault icon in .ico format, or empty. |
| `vaults[].vault.dns_names` | [`StringArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StringArray/index.md) | Host names configured for the vault, if any. |
| `vaults[].main_data_folder` | `string` | The main physical folder of this vault on the server (e.g. C:\Program Files\M-Files\Server Vaults\MyVault). |
| `vaults[].additional_data_folders[]` | repeated [`AdditionalFolder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AdditionalFolder/index.md) | The specification of the additional file data folders. |
| `vaults[].additional_data_folders[].path` | `string` | Path (e.g. "\\servername\sharename\folder"). |
| `vaults[].additional_data_folders[].limit_in_mb` | `uint32` | Data limit in megabytes or zero if no limit. |
| `vaults[].additional_data_folders[].impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the folder. |
| `vaults[].database_info` | [`SQLDatabase`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SQLDatabase/index.md) | The vault's SQL database. |
| `vaults[].database_info.engine` | [`DBEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DBEngine/index.md) | Database engine identification. Values: `DBENGINE_NONE` (0), `DBENGINE_FIREBIRD` (1), `DBENGINE_MS_SQL_SERVER` (2). |
| `vaults[].database_info.server_name` | `string` | The data source i.e. the database server name where the vault's database is residing. This is specified for data service DB engines only. It is empty or unset for embedded databases such as Firebird Embedded. |
| `vaults[].database_info.database_name` | `string` | The catalog i.e. the database name where the vault's data is residing. Allows the database name to differ from the vault display name. This is not specified in the Firebird case. |
| `vaults[].database_info.system_admin_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine for administrative purposes. This contains SYSDBA (System Database Administrator) user name and password. If unset, the default user name and password are used. |
| `vaults[].database_info.basic_user_impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the database engine in basic user operations that do not modify the database structure. This contains DB user name and password. If unset, the default user name and password are used. |
| `vaults[].file_data_storage` | [`FileDataStorage`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FileDataStorage/index.md) | Identifies file data storage to use. Typically specifies that the file data storage is determined automatically. Values: `FILE_DATA_STORAGE_DEFAULT` (0), `FILE_DATA_STORAGE_DISK` (1), `FILE_DATA_STORAGE_DATABASE` (2), `FILE_DATA_STORAGE_EXTERNAL` (3), `FILE_DATA_STORAGE_MASTER` (4). |
| `vaults[].file_data_connection_string` | `string` | The connection string that identifies the location, protocol, and credentials for the file data storage of this vault. For example, this might specify a storage account, a protocol, and a container name for Azure's BLOB Services. Can be unset or empty. |
| `vault_variables[]` | repeated [`VaultVariableArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariableArray/index.md) | The vault variables of each vault, in the order of `vaults`, for every caller. Not valid for offline vaults. |
| `vault_variables[].value[]` | repeated [`VaultVariable`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariable/index.md) | Array of vault variables (VaultVariable). |
| `vault_variables[].value[].name` | `string` | The name of the vault variable. |
| `vault_variables[].value[].value` | `bytes` | The value of the variable in a serialized format. |
| `online_states[]` | repeated `bool` | Whether each vault is online, in the order of `vaults`. |

---

# Vault administration (IRPCVaultAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.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](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 21
- **Proto file:** [`mfiles/IRPCVaultAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVaultAdmin.proto)

<a id="overview"></a>

## Overview

The vault-level maintenance commands of M-Files Admin; the M-Files API's vault management
operations also use [VerifyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md). Use it from
administration tools and automation scripts. To create, back up, take offline or destroy whole
vaults, use [IRPCVaultsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/index.md) 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md).
- **Search indexes**: [GetIndexOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIndexOptions/index.md),
  [ExecuteIndexManagementOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md),
  [RebuildFullTextSearchIndexes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RebuildFullTextSearchIndexes/index.md).
- **Archive and restore content**:
  [ArchiveDocuments](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveDocuments/index.md),
  [ArchiveOldVersions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveOldVersions/index.md),
  [RestoreFromArchive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md),
  [GetDefaultReplicationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetDefaultReplicationConfiguration/index.md).
  Each can first run as a preview (`preview_only`) that changes nothing.
- **Annotations**: [CheckAnnotationsAndRedlining](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckAnnotationsAndRedlining/index.md),
  [EnableAnnotationsAndRedlining](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining/index.md).
- **Microsoft Entra ID (Azure AD) authentication**: the `...AzureAD...` methods,
  [SetVaultVariables](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetVaultVariables/index.md) 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md) 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 `VerifyVault` job 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_archive` or `manage_scheduled_jobs`.

Cancel a running job with
[CancelScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddAutomaticAzureADConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/AddAutomaticAzureADConfiguration/index.md) | 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveDocuments/index.md) | Exports (archives) the objects that match a filter into an archive package, or previews how many would be archived. | `admin` `session` |
| [ArchiveOldVersions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveOldVersions/index.md) | 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckAnnotationsAndRedlining/index.md) | Checks whether the vault has the metadata structure that the annotations and redlining feature needs. | `admin` `session` `idempotent` |
| [CheckForIssue9855Errors](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckForIssue9855Errors/index.md) | 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ContainsAutomaticAzureADConfiguration/index.md) | Checks whether the vault has an automatically created Microsoft Entra ID (Azure AD) authentication configuration. | `admin` `session` `idempotent` |
| [DeleteAutomaticAzureADConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DeleteAutomaticAzureADConfiguration/index.md) | Deletes the automatically created Microsoft Entra ID (Azure AD) authentication configuration of the vault. | `admin` `session` `idempotent` |
| [DismissIssue9855Errors](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DismissIssue9855Errors/index.md) | Marks the recorded file data problems of earlier M-Files versions as dismissed. | `admin` `session` |
| [EnableAnnotationsAndRedlining](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining/index.md) | Enables annotations and redlining in the vault by creating the metadata structure elements that the feature needs. | `admin` `session` `idempotent` |
| [ExecuteIndexManagementOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md) | Runs a management operation on one search index of the vault: rebuild, re-index, activate, enable, disable or delete. | `admin` `session` |
| [GetAzureADProvisioningState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetAzureADProvisioningState/index.md) | 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetDefaultReplicationConfiguration/index.md) | Gets the default cloud storage connection string for the vault's archive and replication jobs. | `admin` `session` `idempotent` |
| [GetIndexOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIndexOptions/index.md) | Lists the search indexes of the vault with their state and the management operations the caller may run on each. | `admin` `session` `idempotent` |
| [GetIssue9855ErrorDetails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIssue9855ErrorDetails/index.md) | Describes the recorded file data problems of earlier M-Files versions in the vault. | `admin` `session` `idempotent` |
| [GetMigrantAuthenticationConfigurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetMigrantAuthenticationConfigurations/index.md) | Lists the authentication configurations of the vault that need to be migrated to the current format. | `admin` `session` |
| [MigrateAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/MigrateAuthenticationConfiguration/index.md) | 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RebuildFullTextSearchIndexes/index.md) | Rebuilds the full-text search indexes of the vault: the metadata index, the file data index or both. | `admin` `session` `idempotent` |
| [RestoreFromArchive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md) | Imports the contents of an archive (or one object of it) into the vault, or previews the import. | `admin` `session` |
| [SetAzureADProvisioningState](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetAzureADProvisioningState/index.md) | Enables or disables user provisioning (SCIM) from Microsoft Entra ID (Azure AD) in the vault. | `admin` `session` `idempotent` |
| [SetVaultVariables](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetVaultVariables/index.md) | Sets the Microsoft Entra ID (Azure AD) consent mode of the vault. | `internal: not for applications` `admin` `session` `idempotent` |
| [VerifyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md) | 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` |

---

# IRPCVaultAdmin.AddAutomaticAzureADConfiguration

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/AddAutomaticAzureADConfiguration/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Creates the automatic Microsoft Entra ID (Azure AD) authentication configuration of the vault
from a completed administrator consent sign-in.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/AddAutomaticAzureADConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-automatic-azure-adconfiguration`
- **Request:** [`AddAutomaticAzureADConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/AddAutomaticAzureADConfiguration/index.md#request)
- **Response:** [`AddAutomaticAzureADConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/AddAutomaticAzureADConfiguration/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **For M-Files components only.** M-Files Admin calls it after the administrator has signed in
  to Entra ID and given consent. Applications should not call it.
- Requires a vault session with full control of the vault.
- `input` is authentication data in M-Files' own binary format; the call fails with "No
  configuration available." unless it comes from the automatic configuration sign-in.

<a id="request"></a>

## Request: AddAutomaticAzureADConfigurationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `input` | `bytes` | Input authentication data. |
| `capabilities` | [`ClientCapabilities`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClientCapabilities/index.md) | The set of client capabilities describing what the client software supports. |
| `capabilities.property_def_searchability` | `bool` | Property definitions can be configured searchable or unsearchable. |
| `capabilities.unmanaged_objects` | `bool` | Client understands unmanaged objects. |
| `capabilities.extension_authentication_data_push` | `bool` | Client supports data push for extension authentications. |
| `capabilities.custom_api_data_push` | `bool` | Client supports server data push for M-Files API & custom implementations. |
| `capabilities.unknown_file_size` | `bool` | Client can handle unknown or estimated file size. |
| `capabilities.typed_metadata_suggestions` | `bool` | Client can handle metadata suggestions to all M-Files types. |
| `capabilities.long_authentication_attempt_identifier` | `bool` | The client handles the long (32-byte) authentication attempt identifier in `AuthenticationAttemptIdentifier.data`. |
| `capabilities.reverse_grouping_level` | `bool` | Client supports reverse grouping levels. |
| `capabilities.object_permissions_for_client` | `bool` | Client supports ObjectPermissionsForClient. |
| `capabilities.hierarchical_object_type_properties` | `bool` | Properties with hierarchy for real object types supported. |
| `capabilities.smart_search` | `bool` | Client supports Smart Search engine type. |
| `capabilities.recurring_notifications` | `bool` | Client supports recurring notifications. |
| `capabilities.smart_search_facets` | `bool` | Client supports smart search facets. |
| `capabilities.vault_role_manage_private_views` | `bool` | Client supports a vault role for managing private views. |
| `capabilities.allow_all_see_deleted_conflict_objects` | `bool` | Client supports that all users can see deleted conflict objects. |
| `capabilities.advanced_password_hashes` | `bool` | Client supports hashing passwords with advanced algorithms, including at least PBKDF2. |
| `capabilities.anonymous_authentication` | `bool` | Client supports anonymous authentication. |
| `capabilities.dataset_deleted_condition` | `bool` | Client supports deleted/not deleted-condition in a dataset definition. |
| `capabilities.unified_password_hashes` | `bool` | Client supports transmitting hashing passwords with the same encoding between all gRPC methods. |
| `capabilities.duplicates_view` | `bool` | Client supports the duplicates view. |
| `capabilities.property_action_state_transition_time` | `bool` | Client supports state transition time setting via state property action. |
| `capabilities.at_mentions` | `bool` | Client supports the @mentions in comment texts. |
| `capabilities.additive_permissions_via_automatic_aclcomponents` | `bool` | Client supports additive permissions via automatic ACL components. |
| `capabilities.vault_level_optimization_jobs` | `bool` | Client supports vault-level optimization jobs. |
| `capabilities.visitor_links_supported` | `bool` | Client supports new interface methods for visitor links. |
| `capabilities.object_type_filter_multi_select_views` | `bool` | Client supports multiple object types as a filter for views and advanced searches. |
| `capabilities.generate_v2_azure_auth_conf_supported` | `bool` | Client supports generating authentication configuration for Azure v2.0 endpoint. |
| `capabilities.structure_item_groups_in_export` | `bool` | Client supports structure item groups in the export job. |
| `capabilities.aino_search` | `bool` | Client supports Aino Search engine type. |
| `capabilities.conversation_history` | `bool` | Client supports conversation history. |
| `capabilities.generate_login_service_auth_conf` | `bool` | Client supports generating authentication configuration for M-Files Login Service. |
| `capabilities.sub_folders_in_views` | `bool` | Client supports subfolders in views. |
| `capabilities.reverse_references_in_pseudo_user_aces` | `bool` | Client supports reverse references in pseudo-user ACEs (Access Control Entries). |
| `capabilities.entity_version_checking_supported` | `bool` | Client supports entity version numbering to track modification conflicts. |
| `capabilities.workflow_descriptions_supported` | `bool` | Client supports workflow descriptions. |
| `capabilities.property_value_metadata_supported` | `bool` | Client supports setting and retrieving property value metadata. |
| `capabilities.object_type_grouping_for_relationships` | `bool` | Client supports object type based grouping for relationships. |
| `capabilities.draft_objects` | `bool` | Client supports draft objects in discovery results. |

<a id="response"></a>

## Response: AddAutomaticAzureADConfigurationResponse

No fields.

---

# IRPCVaultAdmin.ArchiveDocuments

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveDocuments/

Badges: `Administration API / specialized` `admin` `session`

Exports (archives) the objects that match a filter into an archive package, or previews how many
would be archived.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/ArchiveDocuments`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/archive-documents`
- **Request:** [`ArchiveDocumentsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveDocuments/index.md#request)
- **Response:** [`ArchiveDocumentsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveDocuments/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes** unless `preview_only` is true;
  follow it with a session of this vault (see the service overview). A preview runs within the
  call and changes nothing.
- Requires a vault session and the vault right `archive`. Without the server right `manage_jobs`,
  a real (not preview) archive must go to cloud storage (`cloud_storage_connection_string` and
  `cloud_storage_password`), and `target_path` must be empty even in a preview; otherwise it
  fails with "Access denied". With `manage_jobs`, set either `target_path` or the cloud storage
  settings.
- Depending on `archive_job.options`, the objects can be destroyed after they are archived.
- Fails on M-Files editions that do not include archiving.

<a id="request"></a>

## Request: ArchiveDocumentsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `preview_only` | `bool` | True to only count what would be archived; the destination in the job is then ignored and nothing changes. False to start the archiving job. |
| `archive_job` | [`ArchiveDocsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJob/index.md) | The objects to archive (`object_filter`), the destination and the options. |
| `archive_job.target_path` | `string` | Full path to the target file on server. |
| `archive_job.impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the archive target files on server. |
| `archive_job.impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `archive_job.impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `archive_job.impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `archive_job.options` | [`OBJARCHIVINGFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJARCHIVINGFLAGS/index.md) | Bit flags that control the execution of this archiving job. |
| `archive_job.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `archive_job.options.overwrite_existing_files` | `bool` | If present, existing target files are overwritten. If not present, job fails if a target file already exists. |
| `archive_job.options.archive_latest_version_only` | `bool` | If present, only the latest version is archived. |
| `archive_job.options.destroy_archived_objects` | `bool` | If present and archiving full objects, the archived objects are destroyed. |
| `archive_job.options.reset_marked_for_archiving` | `bool` | If present, the 'Marked for archiving' property is reset upon archiving. |
| `archive_job.options.archive_data_files` | `bool` | If present, data files are archived instead of document files. |
| `archive_job.options.create_archive_pdfs` | `bool` | If present, files are also saved as PDF/A. |
| `archive_job.options.archive_destroyed_objects` | `bool` | If present, destroyed objects are archived. |
| `archive_job.options.target_path_is_directory` | `bool` | If present, archive location represents a directory. |
| `archive_job.options.ignore_last_run_timestamp` | `bool` | If present, delta timestamp is not applied (even if provided as non-FILETIME_ZERO). |
| `archive_job.options.ignore_search_conditions` | `bool` | If present, search filter is not applied (even if provided). |
| `archive_job.options.export_drop_out_information` | `bool` | If present, dropout information is exported if a previously exported object is not anymore part of the export set. |
| `archive_job.options.export_content` | `bool` | If present, vault content will be exported. |
| `archive_job.options.export_structure` | `bool` | If present, vault metadata structure will be exported. |
| `archive_job.options.export_value_list_values` | `bool` | If present, values of the selected values lists will be exported. |
| `archive_job.options.export_private_view_settings` | `bool` | If present, private settings of the selected views will be exported. |
| `archive_job.options.export_migrated_as_internal` | `bool` | If present, migrated objects will be exported as internal objects without <externalrepository> element. |
| `archive_job.options.export_workspace_tabs` | `bool` | If present, workspace tabs will be exported. |
| `archive_job.object_filter` | [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | The conditions that limit the object set of this archiving job. |
| `archive_job.object_filter.value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `archive_job.last_run_timestamp_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | If indicated by OBJARCHIVINGFLAG_DELTA, only changes newer than this timestamp are archived. In UTC. |
| `archive_job.structure_items[]` | repeated [`ExportStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportStructureItem/index.md) | The metadata structure items which will be exported. |
| `archive_job.structure_items[].type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | Metadata structure item type. |
| `archive_job.structure_items[].group_selection` | [`StructureItemGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureItemGroup/index.md) | The group selection inside of an item type |
| `archive_job.structure_items[].id` | `int32` | Metadata structure item ID. This is used if the group selection is not used. Otherwise it is MFBuiltInMetadataStructureItemIDAll. Should be used if guid is GUID_NULL. |
| `archive_job.structure_items[].guid` | `string` | Metadata structure item GUID. If not GUID_NULL, should be used instead of lID. This is used e.g. with event handler items. |
| `archive_job.cloud_storage_connection_string` | `string` | Full path to the target file on server. |
| `archive_job.cloud_storage_password` | `string` | Full path to the target file on server. |
| `archive_job.configuration_id` | `string` | Configuration id of this archiving job. |

<a id="response"></a>

## Response: ArchiveDocumentsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the vault's archiving job when `preview_only` is false. |
| `archive_jobs_info` | [`ArchiveDocsJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJobOutputInfo/index.md) | The preview result when `preview_only` is true: the number of objects and bytes. |
| `archive_jobs_info.objects` | `uint32` | The number of archived documents. |
| `archive_jobs_info.bytes` | `int64` | The amount of archived bytes. |

---

# IRPCVaultAdmin.ArchiveOldVersions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveOldVersions/

Badges: `Administration API / specialized` `admin` `session`

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.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/ArchiveOldVersions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/archive-old-versions`
- **Request:** [`ArchiveOldVersionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveOldVersions/index.md#request)
- **Response:** [`ArchiveOldVersionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveOldVersions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes** unless `preview_only` is true;
  follow it with a session of this vault (see the service overview). A preview runs within the
  call and changes nothing.
- Requires a vault session and the vault right `archive`. Running the job for real (not a preview)
  also needs the server right `manage_jobs`; without it the call fails with "Access denied". For
  callers without that right, leave `archivejob.target_file` empty also in a preview.
- Fails on M-Files editions that do not include archiving.

<a id="request"></a>

## Request: ArchiveOldVersionsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `preview_only` | `bool` | True to only count what would be archived; the destination in the job is then ignored and nothing changes. False to start the archiving job. |
| `archivejob` | [`ArchiveOldVersionsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveOldVersionsJob/index.md) | The conditions that select the old versions, the target file on the server and the archiving options. |
| `archivejob.must_be_marked_for_archiving` | `bool` | Condition: Document is marked for archiving. False = condition not effective. |
| `archivejob.must_be_checked_in_before_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | If bCheckedInBefore is true, specifies the condition parameter. |
| `archivejob.has_must_be_at_least_nversions_older` | `bool` | Condition: At least N versions older than the current version. False = condition not effective. |
| `archivejob.must_be_at_least_nversions_older` | `int32` | If bAtLeastNVersionsOlder is true, specifies the condition parameter. |
| `archivejob.has_must_be_at_least_ndays_older` | `bool` | Condition: At least N days older than the current version. False = condition not effective. |
| `archivejob.must_be_at_least_ndays_older` | `int32` | If bAtLeastNDaysOlder is true, specifies the condition parameter. |
| `archivejob.must_not_have_version_tag` | `bool` | Condition: Has no version tag. False = condition not effective. |
| `archivejob.target_file` | `string` | Full path to the target file on server. |
| `archivejob.impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the archive target files on server. |
| `archivejob.impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `archivejob.impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `archivejob.impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `archivejob.options` | [`OBJARCHIVINGFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJARCHIVINGFLAGS/index.md) | Bit flags that control the execution of this archiving job. Note: Currently only OBJARCHIVINGFLAG_OVERWRITEEXISTINGFILES, OBJARCHIVINGFLAG_DESTROYAFTERWARDS, and OBJARCHIVINGFLAG_RESETMFA are supported. |
| `archivejob.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `archivejob.options.overwrite_existing_files` | `bool` | If present, existing target files are overwritten. If not present, job fails if a target file already exists. |
| `archivejob.options.archive_latest_version_only` | `bool` | If present, only the latest version is archived. |
| `archivejob.options.destroy_archived_objects` | `bool` | If present and archiving full objects, the archived objects are destroyed. |
| `archivejob.options.reset_marked_for_archiving` | `bool` | If present, the 'Marked for archiving' property is reset upon archiving. |
| `archivejob.options.archive_data_files` | `bool` | If present, data files are archived instead of document files. |
| `archivejob.options.create_archive_pdfs` | `bool` | If present, files are also saved as PDF/A. |
| `archivejob.options.archive_destroyed_objects` | `bool` | If present, destroyed objects are archived. |
| `archivejob.options.target_path_is_directory` | `bool` | If present, archive location represents a directory. |
| `archivejob.options.ignore_last_run_timestamp` | `bool` | If present, delta timestamp is not applied (even if provided as non-FILETIME_ZERO). |
| `archivejob.options.ignore_search_conditions` | `bool` | If present, search filter is not applied (even if provided). |
| `archivejob.options.export_drop_out_information` | `bool` | If present, dropout information is exported if a previously exported object is not anymore part of the export set. |
| `archivejob.options.export_content` | `bool` | If present, vault content will be exported. |
| `archivejob.options.export_structure` | `bool` | If present, vault metadata structure will be exported. |
| `archivejob.options.export_value_list_values` | `bool` | If present, values of the selected values lists will be exported. |
| `archivejob.options.export_private_view_settings` | `bool` | If present, private settings of the selected views will be exported. |
| `archivejob.options.export_migrated_as_internal` | `bool` | If present, migrated objects will be exported as internal objects without <externalrepository> element. |
| `archivejob.options.export_workspace_tabs` | `bool` | If present, workspace tabs will be exported. |

<a id="response"></a>

## Response: ArchiveOldVersionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the vault's archiving job when `preview_only` is false. |
| `parchiveoldversjoboinfo` | [`ArchiveOldVersionsJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveOldVersionsJobOutputInfo/index.md) | The preview result when `preview_only` is true: affected documents, versions and bytes. |
| `parchiveoldversjoboinfo.objects` | `uint32` | The number of affected documents. |
| `parchiveoldversjoboinfo.object_versions` | `uint32` | The number of archived document versions. |
| `parchiveoldversjoboinfo.bytes` | `int64` | The amount of archived bytes. |

---

# IRPCVaultAdmin.CheckAnnotationsAndRedlining

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckAnnotationsAndRedlining/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Checks whether the vault has the metadata structure that the annotations and redlining feature
needs.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/CheckAnnotationsAndRedlining`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-annotations-and-redlining`
- **Request:** [`CheckAnnotationsAndRedliningRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckAnnotationsAndRedlining/index.md#request)
- **Response:** [`CheckAnnotationsAndRedliningResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckAnnotationsAndRedlining/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session; no special rights (a normal user can call it). Read-only.
- If it returns false, a vault administrator can enable the feature with
  [EnableAnnotationsAndRedlining](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining/index.md).

<a id="request"></a>

## Request: CheckAnnotationsAndRedliningRequest

No fields.

<a id="response"></a>

## Response: CheckAnnotationsAndRedliningResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `enabled` | `bool` | True if all metadata structure elements of the feature exist in the vault. |

<a id="related"></a>

## Related methods

- [EnableAnnotationsAndRedlining](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining/index.md): Enables annotations and redlining in the vault by creating the metadata structure elements that the feature needs.

---

# IRPCVaultAdmin.CheckForIssue9855Errors

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckForIssue9855Errors/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

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.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/CheckForIssue9855Errors`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-for-issue9855-errors`
- **Request:** [`CheckForIssue9855ErrorsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckForIssue9855Errors/index.md#request)
- **Response:** [`CheckForIssue9855ErrorsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckForIssue9855Errors/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `verify_vault`. Read-only.
- Returns 0 when no problems were recorded or when they have been dismissed with
  [DismissIssue9855Errors](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DismissIssue9855Errors/index.md). M-Files Admin
  calls it when it opens a vault; see the details with
  [GetIssue9855ErrorDetails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIssue9855ErrorDetails/index.md) and repair them
  with [VerifyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md).

<a id="request"></a>

## Request: CheckForIssue9855ErrorsRequest

No fields.

<a id="response"></a>

## Response: CheckForIssue9855ErrorsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `potentially_affected_objects` | `int32` | The number of recorded, not dismissed problems; 0 if none. |

<a id="related"></a>

## Related methods

- [DismissIssue9855Errors](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DismissIssue9855Errors/index.md): Marks the recorded file data problems of earlier M-Files versions as dismissed.
- [GetIssue9855ErrorDetails](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIssue9855ErrorDetails/index.md): Describes the recorded file data problems of earlier M-Files versions in the vault.
- [VerifyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md): 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").

---

# IRPCVaultAdmin.ContainsAutomaticAzureADConfiguration

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ContainsAutomaticAzureADConfiguration/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Checks whether the vault has an automatically created Microsoft Entra ID (Azure AD)
authentication configuration.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/ContainsAutomaticAzureADConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/contains-automatic-azure-adconfiguration`
- **Request:** [`ContainsAutomaticAzureADConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ContainsAutomaticAzureADConfiguration/index.md#request)
- **Response:** [`ContainsAutomaticAzureADConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ContainsAutomaticAzureADConfiguration/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

Requires a vault session with full control of the vault (a normal user gets "Access
denied"). Read-only.

<a id="request"></a>

## Request: ContainsAutomaticAzureADConfigurationRequest

No fields.

<a id="response"></a>

## Response: ContainsAutomaticAzureADConfigurationResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `contains_configuration` | `bool` | True if the automatically created configuration exists. |

---

# IRPCVaultAdmin.DeleteAutomaticAzureADConfiguration

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DeleteAutomaticAzureADConfiguration/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Deletes the automatically created Microsoft Entra ID (Azure AD) authentication configuration of
the vault.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/DeleteAutomaticAzureADConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/delete-automatic-azure-adconfiguration`
- **Request:** [`DeleteAutomaticAzureADConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DeleteAutomaticAzureADConfiguration/index.md#request)
- **Response:** [`DeleteAutomaticAzureADConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DeleteAutomaticAzureADConfiguration/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with full control of the vault.
- Changes the vault's authentication configuration.

<a id="request"></a>

## Request: DeleteAutomaticAzureADConfigurationRequest

No fields.

<a id="response"></a>

## Response: DeleteAutomaticAzureADConfigurationResponse

No fields.

---

# IRPCVaultAdmin.DismissIssue9855Errors

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DismissIssue9855Errors/

Badges: `Administration API / specialized` `admin` `session`

Marks the recorded file data problems of earlier M-Files versions as dismissed.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/DismissIssue9855Errors`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/dismiss-issue9855-errors`
- **Request:** [`DismissIssue9855ErrorsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DismissIssue9855Errors/index.md#request)
- **Response:** [`DismissIssue9855ErrorsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/DismissIssue9855Errors/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `verify_vault`.
- Changes the vault: afterwards
  [CheckForIssue9855Errors](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckForIssue9855Errors/index.md) returns 0.
  Calling it again has no further effect.

<a id="request"></a>

## Request: DismissIssue9855ErrorsRequest

No fields.

<a id="response"></a>

## Response: DismissIssue9855ErrorsResponse

No fields.

<a id="related"></a>

## Related methods

- [CheckForIssue9855Errors](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/CheckForIssue9855Errors/index.md): 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.

---

# IRPCVaultAdmin.EnableAnnotationsAndRedlining

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Enables annotations and redlining in the vault by creating the metadata structure elements that
the feature needs.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/enable-annotations-and-redlining`
- **Request:** [`EnableAnnotationsAndRedliningRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining/index.md#request)
- **Response:** [`EnableAnnotationsAndRedliningResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/EnableAnnotationsAndRedlining/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault rights `change_metadata_structure` and
  `license_allows_modifications`.
- Changes the metadata structure of the vault; creates only the elements that are missing, so
  calling it again does no harm.

<a id="request"></a>

## Request: EnableAnnotationsAndRedliningRequest

No fields.

<a id="response"></a>

## Response: EnableAnnotationsAndRedliningResponse

No fields.

---

# IRPCVaultAdmin.ExecuteIndexManagementOperation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/

Badges: `Administration API / specialized` `admin` `session`

Runs a management operation on one search index of the vault: rebuild, re-index, activate,
enable, disable or delete.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/execute-index-management-operation`
- **Request:** [`ExecuteIndexManagementOperationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md#request)
- **Response:** [`ExecuteIndexManagementOperationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `verify_vault`. Activate, enable, disable and
  delete also require the system administrator server role (server right `manage_vaults`).
- Rebuild and re-index start background work by the M-Files indexing service; there is no task ID
  to follow. Re-index works only on combined indexes (`INDEXED_DATA_TYPE_COMBINED`).
- Get the index names and the operations allowed for the caller from
  [GetIndexOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIndexOptions/index.md).

<a id="request"></a>

## Request: ExecuteIndexManagementOperationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `operation_data` | [`IndexManagementOperationData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndexManagementOperationData/index.md) | The index (`name`, as returned by GetIndexOptions) and the operation. |
| `operation_data.name` | [`IndexName`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndexName/index.md) | The name of the index. |
| `operation_data.name.configuration_name` | `string` | The name of the index configuration. |
| `operation_data.name.repository_connection` | `string` | Identifies the external repository connection. |
| `operation_data.name.configuration_type` | [`IndexConfigurationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.IndexConfigurationType/index.md) | The index configuration type (e.g., Shared versus Legacy). Values: `INDEX_CONFIGURATION_TYPE_UNKNOWN` (0), `INDEX_CONFIGURATION_TYPE_LEGACY` (1), `INDEX_CONFIGURATION_TYPE_SHARED` (2), `INDEX_CONFIGURATION_TYPE_ANY` (3). |
| `operation_data.operation` | [`IndexManagementOperation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.IndexManagementOperation/index.md) | Operation to be executed. Values: `INDEX_MANAGEMENT_OPERATION_UNKNOWN` (0), `INDEX_MANAGEMENT_OPERATION_REBUILD` (1), `INDEX_MANAGEMENT_OPERATION_REINDEX` (2), `INDEX_MANAGEMENT_OPERATION_ACTIVATE` (3), `INDEX_MANAGEMENT_OPERATION_ENABLE` (4), `INDEX_MANAGEMENT_OPERATION_DISABLE` (5), `INDEX_MANAGEMENT_OPERATION_DELETE` (6). |

<a id="response"></a>

## Response: ExecuteIndexManagementOperationResponse

No fields.

<a id="related"></a>

## Related methods

- [GetIndexOptions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIndexOptions/index.md): Lists the search indexes of the vault with their state and the management operations the caller may run on each.

---

# IRPCVaultAdmin.GetAzureADProvisioningState

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetAzureADProvisioningState/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets whether user provisioning (SCIM) from Microsoft Entra ID (Azure AD) is enabled in the vault,
and the license type of provisioned users.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/GetAzureADProvisioningState`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-azure-adprovisioning-state`
- **Request:** [`GetAzureADProvisioningStateRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetAzureADProvisioningState/index.md#request)
- **Response:** [`GetAzureADProvisioningStateResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetAzureADProvisioningState/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

Requires a vault session with full control of the vault. Read-only.

<a id="request"></a>

## Request: GetAzureADProvisioningStateRequest

No fields.

<a id="response"></a>

## Response: GetAzureADProvisioningStateResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `provisioning_enabled` | `bool` | True if user provisioning from Entra ID is enabled. |
| `lisence_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license type that new provisioned users get. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |

---

# IRPCVaultAdmin.GetDefaultReplicationConfiguration

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetDefaultReplicationConfiguration/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the default cloud storage connection string for the vault's archive and replication jobs.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/GetDefaultReplicationConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-default-replication-configuration`
- **Request:** [`GetDefaultReplicationConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetDefaultReplicationConfiguration/index.md#request)
- **Response:** [`GetDefaultReplicationConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetDefaultReplicationConfiguration/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault rights `archive` and `restore_from_archive` (a
  normal user gets "Access denied"). Read-only.
- On a server without a default configuration, `connection_string` is empty.

<a id="request"></a>

## Request: GetDefaultReplicationConfigurationRequest

No fields.

<a id="response"></a>

## Response: GetDefaultReplicationConfigurationResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `default_replication_configuration` | [`DefaultReplicationConfiguration`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultReplicationConfiguration/index.md) | The default configuration; `connection_string` is the cloud storage connection string, or empty. |
| `default_replication_configuration.connection_string` | `string` | Connection String for replication via cloud. |

---

# IRPCVaultAdmin.GetIndexOptions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIndexOptions/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the search indexes of the vault with their state and the management operations the caller
may run on each.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/GetIndexOptions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-index-options`
- **Request:** [`GetIndexOptionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIndexOptions/index.md#request)
- **Response:** [`GetIndexOptionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIndexOptions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `see_all_objects` (a normal user gets
  "Access denied"). Read-only.
- `allowed_operations` lists what
  [ExecuteIndexManagementOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md)
  accepts for the index from this caller; a vault administrator without server rights sees only
  `INDEX_MANAGEMENT_OPERATION_REBUILD` on the active indexes.

<a id="request"></a>

## Request: GetIndexOptionsRequest

No fields.

<a id="response"></a>

## Response: GetIndexOptionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `index_options[]` | repeated [`IndexOptions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndexOptions/index.md) | One item per index: its name, the data it indexes, the search engine, whether it is enabled and active, and the operations the caller may run on it. |
| `index_options[].name` | [`IndexName`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndexName/index.md) | The name of the index. |
| `index_options[].name.configuration_name` | `string` | The name of the index configuration. |
| `index_options[].name.repository_connection` | `string` | Identifies the external repository connection. |
| `index_options[].name.configuration_type` | [`IndexConfigurationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.IndexConfigurationType/index.md) | The index configuration type (e.g., Shared versus Legacy). Values: `INDEX_CONFIGURATION_TYPE_UNKNOWN` (0), `INDEX_CONFIGURATION_TYPE_LEGACY` (1), `INDEX_CONFIGURATION_TYPE_SHARED` (2), `INDEX_CONFIGURATION_TYPE_ANY` (3). |
| `index_options[].data_type` | [`IndexedDataType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.IndexedDataType/index.md) | The type of the data the indexer can index. Values: `INDEXED_DATA_TYPE_UNSPECIFIED` (0), `INDEXED_DATA_TYPE_METADATA` (1), `INDEXED_DATA_TYPE_FILE_DATA` (2), `INDEXED_DATA_TYPE_COMBINED` (3). |
| `index_options[].search_engine` | [`SearchEngine`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.SearchEngine/index.md) | Identifies the search engine. Values: `SEARCH_ENGINE_UNSPECIFIED` (0), `SEARCH_ENGINE_DT_SEARCH` (1), `SEARCH_ENGINE_IDOL` (2), `SEARCH_ENGINE_AZURE_SEARCH` (3), `SEARCH_ENGINE_SMART_SEARCH` (4), `SEARCH_ENGINE_AINO_SEARCH` (5), `SEARCH_ENGINE_GOLDFISH` (6). |
| `index_options[].enabled_in_storage` | [`IndexEnabled`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndexEnabled/index.md) | The enabled status of the index in the current storage. |
| `index_options[].enabled_in_storage.enabled` | `bool` | If true, this index is enabled. |
| `index_options[].enabled_in_storage.enabled_for_searching` | `bool` | If true, this index is enabled for searching. The general "Enabled" setting must also be true for the index to actually be enabled for searching. |
| `index_options[].enabled_in_storage.enabled_for_indexing` | `bool` | If true, this index is enabled for indexing. The general "Enabled" setting must also be true for the index to actually be enabled for indexing. |
| `index_options[].enabled_effective` | [`IndexEnabled`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndexEnabled/index.md) | The effective enabled status. |
| `index_options[].enabled_effective.enabled` | `bool` | If true, this index is enabled. |
| `index_options[].enabled_effective.enabled_for_searching` | `bool` | If true, this index is enabled for searching. The general "Enabled" setting must also be true for the index to actually be enabled for searching. |
| `index_options[].enabled_effective.enabled_for_indexing` | `bool` | If true, this index is enabled for indexing. The general "Enabled" setting must also be true for the index to actually be enabled for indexing. |
| `index_options[].active` | `bool` | True, if the index is set as an active index. |
| `index_options[].multi_repository` | `bool` | True, if the physical index can contain multiple repositories. |
| `index_options[].notifications` | [`INDEXNOTIFICATIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.INDEXNOTIFICATIONFLAGS/index.md) | Specifies notifications of the given index. |
| `index_options[].notifications.all` | `bool` | Specifies all flags set; Including any future flags. |
| `index_options[].notifications.reindex_required_propertydef_changed` | `bool` | Re-indexing is required, because of changes in property definitions. |
| `index_options[].notifications.reindex_required_language_changed` | `bool` | Re-indexing is required, because new language package has been installed. |
| `index_options[].notifications.reindex_required_generic` | `bool` | Re-indexing is required. |
| `index_options[].notifications.indexing_in_progress` | `bool` | Indexing is in progress. |
| `index_options[].notifications.rebuild_in_progress` | `bool` | Rebuild is in progress. |
| `index_options[].notifications.dtsearch_active_filedata_index_required` | `bool` | Active filedata index is required. |
| `index_options[].notifications.dtsearch_active_metadata_index_required` | `bool` | Active metadata index is required. |
| `index_options[].exists_implicitly` | `bool` | True, if the index exists implicitly. For example, if the index is default index that exists regardless of configuration. |
| `index_options[].allowed_operations` | [`IndexManagementOperationArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.IndexManagementOperationArray/index.md) | Operations user is allowed to perform with this index. |
| `index_options[].allowed_operations.index_management_operations[]` | repeated [`IndexManagementOperation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.IndexManagementOperation/index.md) | An array of the IndexManagementOperation enums. Values: `INDEX_MANAGEMENT_OPERATION_UNKNOWN` (0), `INDEX_MANAGEMENT_OPERATION_REBUILD` (1), `INDEX_MANAGEMENT_OPERATION_REINDEX` (2), `INDEX_MANAGEMENT_OPERATION_ACTIVATE` (3), `INDEX_MANAGEMENT_OPERATION_ENABLE` (4), `INDEX_MANAGEMENT_OPERATION_DISABLE` (5), `INDEX_MANAGEMENT_OPERATION_DELETE` (6). |

<a id="related"></a>

## Related methods

- [ExecuteIndexManagementOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md): Runs a management operation on one search index of the vault: rebuild, re-index, activate, enable, disable or delete.

---

# IRPCVaultAdmin.GetIssue9855ErrorDetails

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIssue9855ErrorDetails/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Describes the recorded file data problems of earlier M-Files versions in the vault.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/GetIssue9855ErrorDetails`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-issue9855-error-details`
- **Request:** [`GetIssue9855ErrorDetailsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIssue9855ErrorDetails/index.md#request)
- **Response:** [`GetIssue9855ErrorDetailsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetIssue9855ErrorDetails/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `verify_vault`.
- Runs a verification limited to these problems within the call and does not fix anything. If the
  server's verification options for the vault require it, the vault is taken offline for the
  duration, as with [VerifyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md).

<a id="request"></a>

## Request: GetIssue9855ErrorDetailsRequest

No fields.

<a id="response"></a>

## Response: GetIssue9855ErrorDetailsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `poutput` | [`VerifyVaultJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerifyVaultJobOutputInfo/index.md) | The problems found, one message per item in `errors`. |
| `poutput.errors[]` | repeated `string` | Encountered vault errors. |

<a id="related"></a>

## Related methods

- [VerifyVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md): 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").

---

# IRPCVaultAdmin.GetMigrantAuthenticationConfigurations

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetMigrantAuthenticationConfigurations/

Badges: `Administration API / specialized` `admin` `session`

Lists the authentication configurations of the vault that need to be migrated to the current
format.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/GetMigrantAuthenticationConfigurations`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-migrant-authentication-configurations`
- **Request:** [`GetMigrantAuthenticationConfigurationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetMigrantAuthenticationConfigurations/index.md#request)
- **Response:** [`GetMigrantAuthenticationConfigurationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetMigrantAuthenticationConfigurations/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with full control of the vault. Read-only.
- M-Files Admin shows these and migrates each with
  [MigrateAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/MigrateAuthenticationConfiguration/index.md).

<a id="request"></a>

## Request: GetMigrantAuthenticationConfigurationsRequest

No fields.

<a id="response"></a>

## Response: GetMigrantAuthenticationConfigurationsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `configurations[]` | repeated [`AuthenticationConfigurationMigration`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthenticationConfigurationMigration/index.md) | The configurations to migrate, each in its migrated form. Empty if none. |
| `configurations[].scope` | `string` | Scope of the configuration. |
| `configurations[].original_name` | `string` | Name of the original configuration. |
| `configurations[].migrated_configuration` | `string` | Configuration in migrated form. |
| `configurations[].entra_id_tech_cred` | `bool` | Is the original configuration for Entra ID with technical credential settings included. |
| `plugin_infos[]` | repeated [`PluginInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PluginInfo/index.md) | The authentication plugin information of each configuration, in the same order as `configurations`. |
| `plugin_infos[].is_default` | `bool` | True if this is the default configuration. |
| `plugin_infos[].is_scope_independent` | `bool` | True if the plug-in can be used without a configuration scope. |
| `plugin_infos[].name` | `string` | The configuration's name. Send it as `PluginData.plugin_name`. |
| `plugin_infos[].assembly_name` | `string` | The plug-in's implementation, for example `MFiles.AuthenticationProviders.OAuth`. |
| `plugin_infos[].bridge_class_name` | `string` | Internal to the server. |
| `plugin_infos[].system_configuration` | [`NamedValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueArray/index.md) | Where the configuration comes from: `Scope` (send as `PluginData.configuration_scope`) and, for vault-stored configurations, `VaultGUID`. |
| `plugin_infos[].system_configuration.value[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | An array of the NamedValue structures. |
| `plugin_infos[].plugin_configuration` | [`NamedValueArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueArray/index.md) | The plug-in's client-side settings. For an OAuth plug-in these include `AuthorizationEndpoint`, `TokenEndpoint`, `ClientID`, `Scope` and `RedirectURI`. |
| `plugin_infos[].plugin_configuration.value[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | An array of the NamedValue structures. |

<a id="related"></a>

## Related methods

- [MigrateAuthenticationConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/MigrateAuthenticationConfiguration/index.md): Migrates one authentication configuration of the vault to the current format after a successful test sign-in with it.

---

# IRPCVaultAdmin.MigrateAuthenticationConfiguration

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/MigrateAuthenticationConfiguration/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session`

Migrates one authentication configuration of the vault to the current format after a successful
test sign-in with it.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/MigrateAuthenticationConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/migrate-authentication-configuration`
- **Request:** [`MigrateAuthenticationConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/MigrateAuthenticationConfiguration/index.md#request)
- **Response:** [`MigrateAuthenticationConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/MigrateAuthenticationConfiguration/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **For M-Files components only.** M-Files Admin calls it after the administrator has tested the
  migrated configuration by signing in. Applications should not call it.
- Requires a vault session with full control of the vault.
- `auth_data` is the result of the test sign-in in M-Files' own binary format. The call fails if
  the sign-in data does not validate against the migrated configuration.

<a id="request"></a>

## Request: MigrateAuthenticationConfigurationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `configuration` | [`AuthenticationConfigurationMigration`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AuthenticationConfigurationMigration/index.md) | The configuration to migrate, as returned by [GetMigrantAuthenticationConfigurations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/GetMigrantAuthenticationConfigurations/index.md). |
| `configuration.scope` | `string` | Scope of the configuration. |
| `configuration.original_name` | `string` | Name of the original configuration. |
| `configuration.migrated_configuration` | `string` | Configuration in migrated form. |
| `configuration.entra_id_tech_cred` | `bool` | Is the original configuration for Entra ID with technical credential settings included. |
| `auth_data` | `bytes` | Authentication data from the test sign-in with the migrated configuration. |

<a id="response"></a>

## Response: MigrateAuthenticationConfigurationResponse

No fields.

---

# IRPCVaultAdmin.RebuildFullTextSearchIndexes

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RebuildFullTextSearchIndexes/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Rebuilds the full-text search indexes of the vault: the metadata index, the file data index or
both.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/RebuildFullTextSearchIndexes`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/rebuild-full-text-search-indexes`
- **Request:** [`RebuildFullTextSearchIndexesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RebuildFullTextSearchIndexes/index.md#request)
- **Response:** [`RebuildFullTextSearchIndexesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RebuildFullTextSearchIndexes/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `verify_vault`.
- Returns after asking the M-Files indexing service to rebuild; the indexes are rebuilt in the
  background. There is no task ID to follow.
- Fails if rebuilding has been disabled on the server ("Rebuilding the full-text search index has
  been disabled on the server due to performance reasons.").
- To rebuild one specific index, use
  [ExecuteIndexManagementOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md)
  with `INDEX_MANAGEMENT_OPERATION_REBUILD`.

<a id="request"></a>

## Request: RebuildFullTextSearchIndexesRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `rebuild_meta_data_index` | `bool` | True to rebuild the index of the metadata (property values). |
| `rebuild_file_data_index` | `bool` | True to rebuild the index of the file contents. |

<a id="response"></a>

## Response: RebuildFullTextSearchIndexesResponse

No fields.

<a id="related"></a>

## Related methods

- [ExecuteIndexManagementOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ExecuteIndexManagementOperation/index.md): Runs a management operation on one search index of the vault: rebuild, re-index, activate, enable, disable or delete.

---

# IRPCVaultAdmin.RestoreFromArchive

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/

Badges: `Administration API / specialized` `admin` `session`

Imports the contents of an archive (or one object of it) into the vault, or previews the import.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/RestoreFromArchive`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/restore-from-archive`
- **Request:** [`RestoreFromArchiveRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md#request)
- **Response:** [`RestoreFromArchiveResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes** unless `preview_only` is true;
  follow it with a session of this vault (see the service overview). A preview runs within the
  call and changes nothing.
- Requires a vault session and the vault right `restore_from_archive`. Without the server right
  `manage_jobs`, a real (not preview) import must read from cloud storage
  (`cloud_storage_connection_string` and `cloud_storage_password`), and `source_file` must be
  empty even in a preview; otherwise it fails with "Access denied".
- Fails on M-Files editions that do not include archiving.
- The preview writes a summary report (XML). Download it with
  [DownloadScheduledJobOutputFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/index.md)
  (`download_id` = `download_idsummary`), reading blocks until a block is shorter than requested.

<a id="request"></a>

## Request: RestoreFromArchiveRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `preview_only` | `bool` | True to only preview the import and produce a summary report; nothing changes. False to start the import job. |
| `restorefromarchivejob` | [`RestoreFromArchiveJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJob/index.md) | The archive to import (a file on the server or cloud storage), what to import and the import options. |
| `restorefromarchivejob.source_file` | `string` | Full path to the archive file on server. |
| `restorefromarchivejob.impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the archive target file on server. |
| `restorefromarchivejob.impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `restorefromarchivejob.impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `restorefromarchivejob.impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `restorefromarchivejob.restore_full_archive` | `bool` | True to restore the entire contents of the archive. False to restore a specific document only. |
| `restorefromarchivejob.restore_object_id` | `int32` | If bEntireContents is false, specifies the document to restore. |
| `restorefromarchivejob.options` | [`OBJRESTORINGFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJRESTORINGFLAGS/index.md) | Bit flags that control the execution of this restoring job. |
| `restorefromarchivejob.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `restorefromarchivejob.options.target_path_is_directory` | `bool` | If present, archive location represents a directory. |
| `restorefromarchivejob.options.overwrite_existing_versions` | `bool` | If present, replace existing data with the incoming data. |
| `restorefromarchivejob.options.delete_restored_archive` | `bool` | If present, delete the archive once restored. |
| `restorefromarchivejob.options.override_permissions` | `bool` | If present, use the overriding permissions. |
| `restorefromarchivejob.options.restore_check_out_state` | `bool` | DEPRECATED, DO NOT REUSE THE VALUE: const OBJRESTORINGFLAG OBJRESTORINGFLAG_RESETDELTATIMESTAMPS	= ( 1 << 5 );	//!< If present, delta timestamps are reset on export jobs. |
| `restorefromarchivejob.options.do_not_destroy_objects` | `bool` | If present, object destructions are not restored. |
| `restorefromarchivejob.options.use_names_as_alises` | `bool` | If present, incoming names can be used as aliases. |
| `restorefromarchivejob.options.disable_external_object_types` | `bool` | If present, all external connections of imported object types are disabled. |
| `restorefromarchivejob.options.disable_external_user_groups` | `bool` | If present, all external connections of imported user groups are disabled. |
| `restorefromarchivejob.options.disable_event_handlers` | `bool` | If present, all imported event handlers are deactivated. |
| `restorefromarchivejob.options.use_object_type_default_permissions` | `bool` | If present, use the default permissions from object types. |
| `restorefromarchivejob.options.activate_automatic_permissions` | `bool` | If present, new or changed definitions of automatic permissions are activated on objects. |
| `restorefromarchivejob.options.ignore_automatic_permissions` | `bool` | If present, ignore the definitions of automatic permissions from the imported objects. |
| `restorefromarchivejob.options.do_not_update_structure_item_ids` | `bool` | Forces the target vault to keep existing structure item guids. |
| `restorefromarchivejob.options.omit_done_file` | `bool` | Prevents the 'done' file output. |
| `restorefromarchivejob.options.disable_code_in_property_definitions` | `bool` | If present, all custom code in imported property definitions is deactivated. |
| `restorefromarchivejob.options.disable_code_in_workflows` | `bool` | If present, all custom code in imported workflows is deactivated. |
| `restorefromarchivejob.options.allow_signed_code` | `bool` | If present, unchanged or signed custom code is always allowed in import. |
| `restorefromarchivejob.options.import_older_views` | `bool` | If present, the views with an older last modified date and time are imported. |
| `restorefromarchivejob.acl_override` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The overriding ACL. Can be unset. |
| `restorefromarchivejob.acl_override.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `restorefromarchivejob.acl_override.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `restorefromarchivejob.acl_override.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `restorefromarchivejob.acl_override.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `restorefromarchivejob.acl_override.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `restorefromarchivejob.acl_override.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `restorefromarchivejob.restore_structure_items[]` | repeated [`MetadataStructureSelector`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureSelector/index.md) | If not empty, specifies the metadata structure items to restore. |
| `restorefromarchivejob.restore_structure_items[].name` | `string` | A friendly name for the selector. May be used to display the reasoning for the metadata structure item selection for a human (may be included in the preview xml). |
| `restorefromarchivejob.restore_structure_items[].id` | `string` | Optional identificator for the selector. May be used to indicate the reasoning for the metadata structure item selection for a computer (may be included in the preview xml). |
| `restorefromarchivejob.restore_structure_items[].item_type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | Metadata structure item type to select. |
| `restorefromarchivejob.restore_structure_items[].item_guid` | `string` | The GUID of item to select. The primary selector. Not used it the value is GUID_NULL. |
| `restorefromarchivejob.restore_structure_items[].item_alias` | `string` | A semantic alias of the item to select. Applied if the guid is not used. Not used if the value is empty string. |
| `restorefromarchivejob.restore_structure_items[].item_id` | `int32` | Id of the item to select. Will be used if no guid nor alias are specified. |
| `restorefromarchivejob.restore_structure_items[].options` | [`METADATASTRUCTURESELECTORFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.METADATASTRUCTURESELECTORFLAGS/index.md) | Bit flags that control the metadata structure selection. |
| `restorefromarchivejob.cloud_storage_connection_string` | `string` | Transport connection string. |
| `restorefromarchivejob.cloud_storage_password` | `string` | Package encryption password. |
| `restorefromarchivejob.configuration_id` | `string` | Configuration id of this restoring job. |

<a id="response"></a>

## Response: RestoreFromArchiveResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the vault's import job when `preview_only` is false. |
| `prestorefromarchivejoboinfo` | [`RestoreFromArchiveJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJobOutputInfo/index.md) | Not used: always empty. Download the summary report instead. |
| `prestorefromarchivejoboinfo.summary` | `bytes` | The summary report in a serialized format. |
| `download_idsummary` | `int32` | The download ID of the preview's summary report when `preview_only` is true. 0 if there is no report. |
| `file_size_summary` | `int64` | The size of the summary report in bytes. |

<a id="related"></a>

## Related methods

- [IRPCScheduledJobsAdmin.DownloadScheduledJobOutputFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/index.md): Reads a block of a job output file, such as the summary of a restore from archive preview.

---

# IRPCVaultAdmin.SetAzureADProvisioningState

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetAzureADProvisioningState/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Enables or disables user provisioning (SCIM) from Microsoft Entra ID (Azure AD) in the vault.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/SetAzureADProvisioningState`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-azure-adprovisioning-state`
- **Request:** [`SetAzureADProvisioningStateRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetAzureADProvisioningState/index.md#request)
- **Response:** [`SetAzureADProvisioningStateResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetAzureADProvisioningState/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with full control of the vault.
- The vault must already have a provisioning configuration; otherwise the call fails.

<a id="request"></a>

## Request: SetAzureADProvisioningStateRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `provisioning_enabled` | `bool` | True to enable provisioning, false to disable it. |
| `lisence_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license type that new provisioned users get when provisioning is enabled. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |

<a id="response"></a>

## Response: SetAzureADProvisioningStateResponse

No fields.

---

# IRPCVaultAdmin.SetVaultVariables

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetVaultVariables/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Sets the Microsoft Entra ID (Azure AD) consent mode of the vault.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/SetVaultVariables`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-vault-variables`
- **Request:** [`SetVaultVariablesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetVaultVariables/index.md#request)
- **Response:** [`SetVaultVariablesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/SetVaultVariables/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **For M-Files components only.** M-Files Admin calls it when it sets up Entra ID authentication.
  Applications should not call it.
- Requires a vault session with full control of the vault.
- Accepts only the vault variable `AZUREACTIVEDIRECTORYCONSENTMODE`; any other name fails with an
  invalid-argument error. To change other vault variables, use
  [UpdateVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md).

<a id="request"></a>

## Request: SetVaultVariablesRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vaultvariables[]` | repeated [`VaultVariable`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultVariable/index.md) | The vault variables to set; only `AZUREACTIVEDIRECTORYCONSENTMODE` is accepted. |
| `vaultvariables[].name` | `string` | The name of the vault variable. |
| `vaultvariables[].value` | `bytes` | The value of the variable in a serialized format. |
| `update_in_db` | `bool` | True to also store the variables in the vault database. |

<a id="response"></a>

## Response: SetVaultVariablesResponse

No fields.

<a id="related"></a>

## Related methods

- [IRPCVaultsAdmin.UpdateVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultsAdmin/UpdateVault/index.md): Changes the definition of a vault: name and other registration data, data folders, database, file data storage and vault variables.

---

# IRPCVaultAdmin.VerifyVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/

Badges: `Administration API / specialized` `admin` `session`

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").

With `verifyvaultjob.fix_errors` false the vault is not modified; the problems found are reported
in `poutput.errors`. With `fix_errors` true the problems are reported and fixed. If the method
itself fails, the verification or repair logic failed or the vault is too badly damaged to be
fixed by this method.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/VerifyVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/verify-vault`
- **Request:** [`VerifyVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md#request)
- **Response:** [`VerifyVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/VerifyVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Long-running.** With `synchronous` false the call starts a server-level background job and
  returns at once; follow it with a server-level session (see the service overview), and read the
  problems from the job's `output`. With `synchronous` true the call returns when the
  verification is done.
- Requires a vault session and the vault right `verify_vault`.
- If the server's verification options for the vault require it, the vault is taken offline for
  the duration: open sessions are disconnected.
- `verify_file_contents` true also checks the integrity of every file on disk, which can take a
  long time.

<a id="request"></a>

## Request: VerifyVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `verifyvaultjob` | [`VerifyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerifyVaultJob/index.md) | What to verify: the vault (`vault_guid`), whether to fix the problems found (`fix_errors`) and whether to also check the contents of the files on disk (`verify_file_contents`). |
| `verifyvaultjob.vault_guid` | `string` | The GUID of the vault to verify. |
| `verifyvaultjob.fix_errors` | `bool` | True to fix detected errors. |
| `verifyvaultjob.verify_file_contents` | `bool` | True to verify the integrity of the data files on disk. |
| `synchronous` | `bool` | True to verify within the call. False to start a background job and return at once. |

<a id="response"></a>

## Response: VerifyVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the server-level verification job when `synchronous` is false. |
| `poutput` | [`VerifyVaultJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerifyVaultJobOutputInfo/index.md) | The problems found, one message per item in `errors`, when `synchronous` is true. Empty if the vault has no problems. |
| `poutput.errors[]` | repeated `string` | Encountered vault errors. |

---

# Server login accounts (IRPCLoginsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/

Manages the server's login accounts: list, add, modify and remove logins, force logouts, look up
Windows accounts and groups, and handle password resets.

Use this interface to add, modify and delete logins.

- **gRPC service:** `MFiles.IRPCLoginsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 19
- **Proto file:** [`mfiles/IRPCLoginsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCLoginsAdmin.proto)

<a id="overview"></a>

## Overview

A login account is the server-level identity (M-Files or Windows authentication, server roles,
license type) that user accounts in vaults are linked to. This is the service behind the
"Login Accounts" node of M-Files Admin. Applications rarely need it; provisioning and audit
scripts can use it.

**Sessions and rights.** A server-level session is enough (log in with `login_data.vault_guid` =
`{00000000-0000-0000-0000-000000000000}`); a vault session works too. Most methods require the
**system administrator** server role (server right `manage_logins` in
[ServerAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAccess/index.md)); a vault administrator does not have it, and the call
fails with "Access denied. You do not have the server-level access rights required by this
operation." (0x800400A8, 0x800407E4). Exceptions:

- [GetLogins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogins/index.md) and
  [GetLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/index.md) also serve callers without server rights,
  with a narrower result (see their remarks). This is why a vault administrator can list logins.
- [CreatePasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md) and
  [ResetPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/index.md) need no session at all: they are
  the "forgot password" flow of M-Files Web.

Methods by task:

- **Read logins**: [GetLogins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogins/index.md),
  [GetLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/index.md),
  [GetLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLoginsWithSessions/index.md).
- **Change logins**: [AddLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/AddLogin/index.md),
  [ModifyLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ModifyLogin/index.md),
  [RemoveLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/RemoveLogin/index.md),
  [ForceLogout](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ForceLogout/index.md).
- **Passwords**: [GetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md),
  [SetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md) (copy a password between
  servers),
  [CreatePasswordResetRequestAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin/index.md),
  [CreatePasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md),
  [ResetPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/index.md).
- **Windows and Active Directory lookups** (for picking Windows accounts and groups):
  [GetDomainName](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetDomainName/index.md),
  [GetComputerName](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetComputerName/index.md),
  [GetAllDomains](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetAllDomains/index.md),
  [GetOrganizationalUnitsForDomain](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetOrganizationalUnitsForDomain/index.md),
  [GetWindowsGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroups/index.md),
  [GetWindowsGroupMembers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroupMembers/index.md),
  [GetFullNameAndEmail](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetFullNameAndEmail/index.md).

A login is identified by its account name: the user name for M-Files logins, the down-level logon
name (domain and user name separated by a backslash) for Windows logins. Server roles and the enabled state are in [SRVROLES](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md):
a login without `can_log_in` is disabled.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/AddLogin/index.md) | Adds a login account to the server. | `admin` `session` |
| [CreatePasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md) | Starts the "forgot password" flow for an M-Files login: sends the user an e-mail with a password reset link. | `admin` `no session` |
| [CreatePasswordResetRequestAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin/index.md) | Creates a password reset link for an M-Files login, returns it, and optionally e-mails it to the user. | `admin` `session` |
| [ForceLogout](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ForceLogout/index.md) | Ends all sessions of the given login accounts in every vault on the server. | `admin` `session` |
| [GetAllDomains](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetAllDomains/index.md) | Lists the Windows domains that the server computer can reach, including its own. | `admin` `session` `idempotent` |
| [GetComputerName](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetComputerName/index.md) | Gets the name of the server computer. | `admin` `session` |
| [GetDomainName](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetDomainName/index.md) | Gets the Windows domain of the server computer, or the computer name if it is not in a domain. | `admin` `session` `idempotent` |
| [GetFullNameAndEmail](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetFullNameAndEmail/index.md) | Looks up the full name and e-mail address of a Windows account in its directory. | `admin` `session` `idempotent` |
| [GetLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/index.md) | Gets one login account by account name. | `admin` `session` |
| [GetLogins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogins/index.md) | Gets the login accounts the caller is allowed to see: all of them for system administrators, otherwise those linked to vaults the caller administers. | `admin` `session` `idempotent` |
| [GetLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLoginsWithSessions/index.md) | Gets the login accounts that currently have open sessions on the server. | `admin` `session` `idempotent` |
| [GetOrganizationalUnitsForDomain](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetOrganizationalUnitsForDomain/index.md) | Lists the organizational units of a Windows domain. | `admin` `session` `idempotent` |
| [GetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md) | Gets the encrypted password hash of an M-Files login, for copying the password to another server with [SetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md). | `admin` `session` `idempotent` |
| [GetWindowsGroupMembers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroupMembers/index.md) | Lists the users and groups that are members of a Windows group. | `admin` `session` `idempotent` |
| [GetWindowsGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroups/index.md) | Lists Windows groups that the server can see: local groups and domain groups. | `admin` `session` `idempotent` |
| [ModifyLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ModifyLogin/index.md) | Changes a login account: its server roles and enabled state, and optionally its password, full name, e-mail address and license type. | `admin` `session` `idempotent` |
| [RemoveLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/RemoveLogin/index.md) | Removes a login account from the server. | `admin` `session` |
| [ResetPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/index.md) | Completes the "forgot password" flow: sets a new password for a login with the values from the password reset link. | `admin` `no session` |
| [SetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md) | Sets the password of an M-Files login from a password hash, for example one read with [GetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md) on another server. | `admin` `session` `idempotent` |

---

# IRPCLoginsAdmin.AddLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/AddLogin/

Badges: `Administration API / specialized` `admin` `session`

Adds a login account to the server.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/AddLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-login`
- **Request:** [`AddLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/AddLogin/index.md#request)
- **Response:** [`AddLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/AddLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- On servers that use vault login accounts, only logins with the system administrator role can
  be added at server level.
- For an M-Files login, provide the password in `password_info`.

<a id="request"></a>

## Request: AddLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `login` | [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The new login. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `login.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `login.domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `login.user_name` | `string` | User name. Cannot be unset. |
| `login.options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `login.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `login.options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `login.options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `login.options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `login.full_name` | `string` | The full name of the user. May be unset. |
| `login.email_address` | `string` | The email address of the user. May be unset. |
| `login.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `login.credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `login.client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `login.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |
| `password_hash` | `string` | Deprecated; leave empty and use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The encrypted password hash of an M-Files login. |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |

<a id="response"></a>

## Response: AddLoginResponse

No fields.

---

# IRPCLoginsAdmin.CreatePasswordResetRequest

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/

Badges: `Administration API / specialized` `admin` `no session`

Starts the "forgot password" flow for an M-Files login: sends the user an e-mail with a
password reset link.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-password-reset-request`
- **Request:** [`CreatePasswordResetRequestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md#request)
- **Response:** [`CreatePasswordResetRequestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Needs no session. The reset URL is not returned to the caller; it is only e-mailed. System
  administrators can get the URL with
  [CreatePasswordResetRequestAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin/index.md).
- `site_url` must match the M-Files Web address configured for a vault on the server (with
  https if that address uses https); otherwise the call fails with "The parameter is
  incorrect.".
- Fails when password reset is disabled on the server, the login is not found, is a Windows
  login, has no e-mail address, has the system administrator role, or a request was sent for it
  very recently.
- On servers with vault login accounts, the vault given by `vault_guid` (or found from the host
  of `site_url`) is tried first.
- The link is valid for 7 days by default. Complete the reset with
  [ResetPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/index.md).

<a id="request"></a>

## Request: CreatePasswordResetRequestRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The login's account name. Leave empty to identify the login by `account_email_address`. |
| `account_email_address` | `string` | Used only when `account_name` is empty; exactly one login must have this address. |
| `site_url` | `string` | The M-Files Web page that handles the reset. The link is this URL with `username`, `hash` and `expiration` query parameters added. |
| `send_email` | `bool` | True if an e-mail containing the password reset URL should be sent to the user. |
| `vault_guid` | `string` | Optional vault for servers that use vault login accounts. |

<a id="response"></a>

## Response: CreatePasswordResetRequestResponse

No fields.

<a id="related"></a>

## Related methods

- [CreatePasswordResetRequestAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin/index.md): Creates a password reset link for an M-Files login, returns it, and optionally e-mails it to the user.
- [ResetPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/index.md): Completes the "forgot password" flow: sets a new password for a login with the values from the password reset link.

---

# IRPCLoginsAdmin.CreatePasswordResetRequestAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin/

Badges: `Administration API / specialized` `admin` `session`

Creates a password reset link for an M-Files login, returns it, and optionally e-mails it to
the user.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-password-reset-request-admin`
- **Request:** [`CreatePasswordResetRequestAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin/index.md#request)
- **Response:** [`CreatePasswordResetRequestAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequestAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- The same rules as in
  [CreatePasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md) apply.

<a id="request"></a>

## Request: CreatePasswordResetRequestAdminRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The name of the login account whose password should be reset. |
| `account_email_address` | `string` | The e-mail address of the login account whose password should be reset. |
| `site_url` | `string` | The site URL used in forming the password reset URL. |
| `send_email` | `bool` | True to also e-mail the link to the user. |
| `vault_guid` | `string` | The vault to try login account reset request in. |

<a id="response"></a>

## Response: CreatePasswordResetRequestAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `password_reset_url` | `string` | The reset link. |

<a id="related"></a>

## Related methods

- [CreatePasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md): Starts the "forgot password" flow for an M-Files login: sends the user an e-mail with a password reset link.

---

# IRPCLoginsAdmin.ForceLogout

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ForceLogout/

Badges: `Administration API / specialized` `admin` `session`

Ends all sessions of the given login accounts in every vault on the server.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/ForceLogout`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/force-logout`
- **Request:** [`ForceLogoutRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ForceLogout/index.md#request)
- **Response:** [`ForceLogoutResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ForceLogout/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- The users are logged out at once; their clients must log in again.

<a id="request"></a>

## Request: ForceLogoutRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_names[]` | repeated `string` | The account names of the logins to log out. |

<a id="response"></a>

## Response: ForceLogoutResponse

No fields.

---

# IRPCLoginsAdmin.GetAllDomains

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetAllDomains/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the Windows domains that the server computer can reach, including its own.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetAllDomains`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-all-domains`
- **Request:** [`GetAllDomainsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetAllDomains/index.md#request)
- **Response:** [`GetAllDomainsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetAllDomains/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).

<a id="request"></a>

## Request: GetAllDomainsRequest

No fields.

<a id="response"></a>

## Response: GetAllDomainsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domains[]` | repeated `string` | Receives domain names. |

---

# IRPCLoginsAdmin.GetComputerName

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetComputerName/

Badges: `Administration API / specialized` `admin` `session`

Gets the name of the server computer.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetComputerName`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-computer-name`
- **Request:** [`GetComputerNameRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetComputerName/index.md#request)
- **Response:** [`GetComputerNameResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetComputerName/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).

<a id="request"></a>

## Request: GetComputerNameRequest

No fields.

<a id="response"></a>

## Response: GetComputerNameResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `computer` | `string` | Receives the computer name. |

---

# IRPCLoginsAdmin.GetDomainName

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetDomainName/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the Windows domain of the server computer, or the computer name if it is not in a domain.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetDomainName`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-domain-name`
- **Request:** [`GetDomainNameRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetDomainName/index.md#request)
- **Response:** [`GetDomainNameResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetDomainName/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`). Denied for
  other callers.

<a id="request"></a>

## Request: GetDomainNameRequest

No fields.

<a id="response"></a>

## Response: GetDomainNameResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domain` | `string` | The domain name, or the computer name when the server is not in a domain. |

---

# IRPCLoginsAdmin.GetFullNameAndEmail

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetFullNameAndEmail/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Looks up the full name and e-mail address of a Windows account in its directory.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetFullNameAndEmail`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-full-name-and-email`
- **Request:** [`GetFullNameAndEmailRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetFullNameAndEmail/index.md#request)
- **Response:** [`GetFullNameAndEmailResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetFullNameAndEmail/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- Reads the directory (Active Directory, or the user synchronization plug-in configured for the
  domain), not the M-Files login. Use [GetLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/index.md) for the
  values stored in M-Files.

<a id="request"></a>

## Request: GetFullNameAndEmailRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The Windows account in `DOMAIN\user` form. |

<a id="response"></a>

## Response: GetFullNameAndEmailResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `full_name` | `string` | Receives the full name. |
| `email` | `string` | Receives the email address. |

<a id="related"></a>

## Related methods

- [GetLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/index.md): Gets one login account by account name.

---

# IRPCLoginsAdmin.GetLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/

Badges: `Administration API / specialized` `admin` `session`

Gets one login account by account name.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-login`
- **Request:** [`GetLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/index.md#request)
- **Response:** [`GetLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- An unknown account fails with "Not found.".

<a id="request"></a>

## Request: GetLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name: the user name of an M-Files login or `DOMAIN\user`. |

<a id="response"></a>

## Response: GetLoginResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `plogin` | [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The login account. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `plogin.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `plogin.domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `plogin.user_name` | `string` | User name. Cannot be unset. |
| `plogin.options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `plogin.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `plogin.options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `plogin.options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `plogin.options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `plogin.full_name` | `string` | The full name of the user. May be unset. |
| `plogin.email_address` | `string` | The email address of the user. May be unset. |
| `plogin.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `plogin.credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `plogin.client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `plogin.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |

---

# IRPCLoginsAdmin.GetLogins

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogins/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the login accounts the caller is allowed to see: all of them for system administrators,
otherwise those linked to vaults the caller administers.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetLogins`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-logins`
- **Request:** [`GetLoginsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogins/index.md#request)
- **Response:** [`GetLoginsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogins/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it; the result depends on the caller:
  - with the server right `manage_logins` (system administrator role): all logins;
  - otherwise: only the logins that are linked to a user account in a vault where the caller has
    a user account with the vault right `manage_users` (vault administrators have it). All online
    vaults of the server are checked, whatever vault the session is in.
- A caller who administers no vault gets an empty list, not an error.
- So a vault administrator without server rights gets the logins of its vault's users, in a
  vault session and in a server-level session alike.

<a id="request"></a>

## Request: GetLoginsRequest

No fields.

<a id="response"></a>

## Response: GetLoginsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The login accounts. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `values[].account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `values[].domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `values[].user_name` | `string` | User name. Cannot be unset. |
| `values[].options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `values[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `values[].options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `values[].options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `values[].options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `values[].full_name` | `string` | The full name of the user. May be unset. |
| `values[].email_address` | `string` | The email address of the user. May be unset. |
| `values[].license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `values[].credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `values[].client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `values[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |

<a id="related"></a>

## Related methods

- [GetLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLoginsWithSessions/index.md): Gets the login accounts that currently have open sessions on the server.

---

# IRPCLoginsAdmin.GetLoginsWithSessions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLoginsWithSessions/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the login accounts that currently have open sessions on the server.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetLoginsWithSessions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-logins-with-sessions`
- **Request:** [`GetLoginsWithSessionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLoginsWithSessions/index.md#request)
- **Response:** [`GetLoginsWithSessionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLoginsWithSessions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`). Denied for
  other callers.

<a id="request"></a>

## Request: GetLoginsWithSessionsRequest

No fields.

<a id="response"></a>

## Response: GetLoginsWithSessionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The logins with sessions. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `values[].account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `values[].domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `values[].user_name` | `string` | User name. Cannot be unset. |
| `values[].options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `values[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `values[].options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `values[].options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `values[].options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `values[].full_name` | `string` | The full name of the user. May be unset. |
| `values[].email_address` | `string` | The email address of the user. May be unset. |
| `values[].license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `values[].credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `values[].client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `values[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |

<a id="related"></a>

## Related methods

- [GetLogins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetLogins/index.md): Gets the login accounts the caller is allowed to see: all of them for system administrators, otherwise those linked to vaults the caller administers.

---

# IRPCLoginsAdmin.GetOrganizationalUnitsForDomain

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetOrganizationalUnitsForDomain/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the organizational units of a Windows domain.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetOrganizationalUnitsForDomain`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-organizational-units-for-domain`
- **Request:** [`GetOrganizationalUnitsForDomainRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetOrganizationalUnitsForDomain/index.md#request)
- **Response:** [`GetOrganizationalUnitsForDomainResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetOrganizationalUnitsForDomain/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).

<a id="request"></a>

## Request: GetOrganizationalUnitsForDomainRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domain` | `string` | The domain name in NetBIOS form, for example `CONTOSO`. |

<a id="response"></a>

## Response: GetOrganizationalUnitsForDomainResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `ous[]` | repeated [`DirectoryItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DirectoryItem/index.md) | Receives organizational units. |
| `ous[].distinguished_name` | `string` | The distinguished name of the directory item, e.g. "CN=gr01,OU=orgunit,DC=domain,DC=com" |
| `ous[].display_name` | `string` | Name of the directory object as displayed in user interface. |

---

# IRPCLoginsAdmin.GetPasswordHash

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the encrypted password hash of an M-Files login, for copying the password to another
server with [SetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md).

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetPasswordHash`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-password-hash`
- **Request:** [`GetPasswordHashRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md#request)
- **Response:** [`GetPasswordHashResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`). Denied for
  other callers.
- The hash is encrypted with the public key the caller provides; `PASSWORD_ENCRYPTION_UNENCRYPTED`
  fails with "The parameter is incorrect.".

<a id="request"></a>

## Request: GetPasswordHashRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `password_encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | How to encrypt the hash for transit: set `PASSWORD_ENCRYPTION_AES256`. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
| `public_key` | `bytes` | The caller's public key; the hash is encrypted with it. |
| `account_name` | `string` | The name of the account to get password hash from. |

<a id="response"></a>

## Response: GetPasswordHashResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `password_hash` | `string` | Deprecated; filled only for old clients. Use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The encrypted hash with its hash algorithm and salt. |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |

<a id="related"></a>

## Related methods

- [SetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md): Sets the password of an M-Files login from a password hash, for example one read with [GetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md) on another server.

---

# IRPCLoginsAdmin.GetWindowsGroupMembers

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroupMembers/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the users and groups that are members of a Windows group.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetWindowsGroupMembers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-windows-group-members`
- **Request:** [`GetWindowsGroupMembersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroupMembers/index.md#request)
- **Response:** [`GetWindowsGroupMembersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroupMembers/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).

<a id="request"></a>

## Request: GetWindowsGroupMembersRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `group_name` | `string` | The group in `DOMAIN\group` form. |
| `egim` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` for the direct members only, or `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` to include the members of nested groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |

<a id="response"></a>

## Response: GetWindowsGroupMembersResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `users[]` | repeated `string` | Receives the names of the users (e.g. "DOMAIN\user"). |
| `groups[]` | repeated `string` | Receives the names of the groups (e.g. "DOMAIN\Group 1"). |

---

# IRPCLoginsAdmin.GetWindowsGroups

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroups/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists Windows groups that the server can see: local groups and domain groups.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/GetWindowsGroups`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-windows-groups`
- **Request:** [`GetWindowsGroupsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroups/index.md#request)
- **Response:** [`GetWindowsGroupsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetWindowsGroups/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- The number of groups is limited by server configuration; `group_limit_exceeded` tells
  whether the list was cut. Narrow the search with `domain_name` and
  `organizational_unit_name_dn`.

<a id="request"></a>

## Request: GetWindowsGroupsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domain_name` | `string` | The domain to search, or unset for all groups. |
| `organizational_unit_name_dn` | `string` | The distinguished name of an organizational unit to search in (see [GetOrganizationalUnitsForDomain](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetOrganizationalUnitsForDomain/index.md)), or unset to search from the domain level. |
| `search_sub_items` | `bool` | True to search the sub-units too. Used only when `domain_name` is set. |

<a id="response"></a>

## Response: GetWindowsGroupsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `groups[]` | repeated `string` | Receives the names of the groups (e.g. "DOMAIN\Domain Users"). |
| `group_limit_exceeded` | `bool` | Set to true if the result set does not contain all groups. |

---

# IRPCLoginsAdmin.ModifyLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ModifyLogin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Changes a login account: its server roles and enabled state, and optionally its password, full
name, e-mail address and license type.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/ModifyLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-login`
- **Request:** [`ModifyLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ModifyLogin/index.md#request)
- **Response:** [`ModifyLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ModifyLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- `srvroles` is always written; send the complete set (including `can_log_in` to keep the login
  enabled). The other fields are written only when `change_password` or `update_other_fields`
  is true.
- Changing the license type fails if no license of that type is available.
- On servers that use vault login accounts, a login that is not a system administrator can only
  be disabled or set to no license here.
- `update_client_id` and `client_id` are ignored by this method.
- By default, the linked user accounts in the online vaults are refreshed after a change.

<a id="request"></a>

## Request: ModifyLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The name of the account to modify. |
| `srvroles` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | The complete new server roles, including `can_log_in`. |
| `srvroles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `srvroles.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `srvroles.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `srvroles.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `change_password` | `bool` | True to set the password from `password_info`. |
| `password_hash` | `string` | Deprecated; leave empty and use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The new encrypted password hash. Used only when `change_password` is true. |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
| `update_other_fields` | `bool` | True to write `full_name`, `email_address` and `licensetype`. |
| `full_name` | `string` | The full name of the account. |
| `email_address` | `string` | The email address of the account. |
| `licensetype` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The license type of the account. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `update_client_id` | `bool` | Ignored. |
| `client_id` | `string` | Ignored. |

<a id="response"></a>

## Response: ModifyLoginResponse

No fields.

---

# IRPCLoginsAdmin.RemoveLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/RemoveLogin/

Badges: `Administration API / specialized` `admin` `session`

Removes a login account from the server.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/RemoveLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-login`
- **Request:** [`RemoveLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/RemoveLogin/index.md#request)
- **Response:** [`RemoveLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/RemoveLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- The user accounts linked to the login in vaults are not removed; remove them per vault if
  needed.

<a id="request"></a>

## Request: RemoveLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name of the login to remove. |

<a id="response"></a>

## Response: RemoveLoginResponse

No fields.

---

# IRPCLoginsAdmin.ResetPassword

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/

Badges: `Administration API / specialized` `admin` `no session`

Completes the "forgot password" flow: sets a new password for a login with the values from the
password reset link.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/ResetPassword`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-password`
- **Request:** [`ResetPasswordRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/index.md#request)
- **Response:** [`ResetPasswordResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/ResetPassword/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Needs no session. The `account_name`, `expiration_time` and `reset_password_hash` come from
  the link's `username`, `expiration` and `hash` query parameters
  ([CreatePasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md)).
- An invalid or expired link fails with "Changing the password failed.".
- Failed attempts count toward the server's login attack protection, like failed logins; a
  blocked address or account fails until the block ends.
- **Pitfall:** set `password_format` to `PASSWORD_FORMAT_SEE_OTHER_PARAMS`. The proto3 default
  selects a deprecated format that overrides the other password fields.

<a id="request"></a>

## Request: ResetPasswordRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The name of the login account whose password should be reset. |
| `expiration_time` | `string` | The time when this password request expires. |
| `reset_password_hash` | `string` | The hash used to confirm that this is a valid password reset. |
| `new_password` | `string` | The new password for the login account. |
| `vault_guid` | `string` | Optional vault for servers that use vault login accounts. |
| `password_format` | [`PasswordFormat`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordFormat/index.md) | Set `PASSWORD_FORMAT_SEE_OTHER_PARAMS`. The other values, including the default, are deprecated. Values: `PASSWORD_FORMAT_MD5_HASH_ENCRYPTED` (0), `PASSWORD_FORMAT_PLAIN_TEXT` (1), `PASSWORD_FORMAT_SEE_OTHER_PARAMS` (2). |
| `password_encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption used for the passwords in transit. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
| `password_unhashed` | `bool` | True if `new_password` is the password itself (possibly encrypted), not a hash. If false, the hash must use `password_hash_algorithm_desired`. |
| `password_hash_algorithm_desired` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Algorithm to be used to hash the new password in the database. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `new_password_salt` | `string` | The salt of a hashed `new_password`. Ignored when `password_unhashed` is true; the server then generates the salt. |

<a id="response"></a>

## Response: ResetPasswordResponse

No fields.

<a id="related"></a>

## Related methods

- [CreatePasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/CreatePasswordResetRequest/index.md): Starts the "forgot password" flow for an M-Files login: sends the user an e-mail with a password reset link.

---

# IRPCLoginsAdmin.SetPasswordHash

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Sets the password of an M-Files login from a password hash, for example one read with
[GetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md) on another server.

- **Service:** [Server login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) `MFiles.IRPCLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCLoginsAdmin/SetPasswordHash`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-password-hash`
- **Request:** [`SetPasswordHashRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md#request)
- **Response:** [`SetPasswordHashResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_logins`).
- An unknown login fails with "Not found.". Works only for M-Files logins.

<a id="request"></a>

## Request: SetPasswordHashRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The name of the account to set password hash to. |
| `password_hash` | `string` | Deprecated; leave empty and use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The password hash with its algorithm, salt and transit encryption. |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |

<a id="response"></a>

## Response: SetPasswordHashResponse

No fields.

<a id="related"></a>

## Related methods

- [GetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/GetPasswordHash/index.md): Gets the encrypted password hash of an M-Files login, for copying the password to another server with [SetPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/SetPasswordHash/index.md).

---

# Vault login accounts (IRPCVaultLoginsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/

Manages vault login accounts: login accounts stored in one vault, used on servers that have
vault login accounts enabled, such as M-Files Cloud.

Use this interface to add, modify and delete vault logins.

- **gRPC service:** `MFiles.IRPCVaultLoginsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 17
- **Proto file:** [`mfiles/IRPCVaultLoginsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCVaultLoginsAdmin.proto)

<a id="overview"></a>

## Overview

A login account is what a person or application authenticates with: account type (M-Files or
Windows), user name, password, license type, full name and email
([Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md)). Normally login accounts belong to the server and are managed by
system administrators with [IRPCLoginsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md). On a server with
**vault login accounts** enabled, each vault keeps its own login accounts in the vault, and
vault administrators manage them with this service. Either way, a login needs a user account in
the vault ([IRPCUsersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)) to use the vault; see the table in
the [IRPCUsersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) overview.

- **Availability.** Vault login accounts are a server-wide setting. Check it anonymously with
  [GetServerCapabilities](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetServerCapabilities/index.md):
  `server_capabilities.vault_login_accounts`. An M-Files Cloud server returned true; a default
  on-premises server returns false. When it is false, **every method of this service** fails
  with "This operation is currently not available. The registry key for enabling vault-specific
  login accounts needs to be set first." (error code 0x8004093A), before the session is checked.
- **Session and rights.** Requires a vault session; the methods work on the logins of that
  vault. Most methods need the vault right `manage_users`
  ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); the server role system administrator is not
  needed. A server can be configured to make vault login accounts read-only for vault
  administrators: then
  [AddVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin/index.md),
  [ModifyVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin/index.md),
  [ModifyVaultLoginEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/index.md) and
  [RemoveVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/RemoveVaultLogin/index.md) also need the system
  administrator server role (server right `manage_logins`).
- **Server and vault logins together.** When a vault login and a server login have the same
  account name, the vault login is used for that vault. A vault login can never have the system
  administrator role. While vault login accounts are enabled, server-level
  [AddLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/AddLogin/index.md) accepts only system administrators.
- **Logins with an External ID** (`Login.external_id`) are maintained by identity
  synchronization (M-Files Manage); removing or renaming them here fails.

Methods by task (the server-level equivalents are in
[IRPCLoginsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md)):

- **Read:** [GetVaultLogins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogins/index.md),
  [GetVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogin/index.md),
  [GetVaultLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/index.md).
- **Add, change, remove:** [AddVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin/index.md),
  [ModifyVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin/index.md),
  [ModifyVaultLoginEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/index.md),
  [RemoveVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/RemoveVaultLogin/index.md),
  [ForceLogoutVaultLoginSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions/index.md).
- **Passwords:**
  [CreateVaultLoginPasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest/index.md),
  [ResetVaultLoginPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword/index.md),
  [GetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash/index.md),
  [SetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash/index.md).
- **Directory lookups for importing Windows accounts:**
  [GetAllDomainsInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetAllDomainsInVault/index.md),
  [GetOrganizationalUnitsForDomainInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetOrganizationalUnitsForDomainInVault/index.md),
  [GetWindowsGroupsInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault/index.md),
  [GetWindowsGroupMembersInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupMembersInVault/index.md),
  [GetFullNameAndEmailInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetFullNameAndEmailInVault/index.md).
  They read the domain directory, or the vault's default user synchronization plugin when one is
  configured for the domain. A server can be configured to use only that plugin for callers
  without the server right `manage_logins`.

Typical provisioning on such a server:
[AddVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin/index.md), then
[AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) with `login_name` set to the new login's account
name.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin/index.md) | Adds a login account to the vault. | `admin` `session` |
| [CreateVaultLoginPasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest/index.md) | Creates a password reset link for an M-Files login of the vault, and optionally emails it to the login's email address. | `admin` `session` |
| [ForceLogoutVaultLoginSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions/index.md) | Logs out all sessions of the given login accounts in this vault. | `admin` `session` |
| [GetAllDomainsInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetAllDomainsInVault/index.md) | Lists the domains whose accounts can be imported: the server's own domain and the domains it can reach. | `admin` `session` `idempotent` |
| [GetFullNameAndEmailInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetFullNameAndEmailInVault/index.md) | Looks up the full name and email address of a Windows account in the directory. | `admin` `session` `idempotent` |
| [GetOrganizationalUnitsForDomainInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetOrganizationalUnitsForDomainInVault/index.md) | Lists the organizational units of a domain. | `admin` `session` `idempotent` |
| [GetVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogin/index.md) | Gets one vault login by account name. | `admin` `session` |
| [GetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash/index.md) | Reads the password hash of a vault login, encrypted with a public key that the caller supplies. | `admin` `session` `idempotent` |
| [GetVaultLogins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogins/index.md) | Gets all login accounts stored in the vault. | `admin` `session` `idempotent` |
| [GetVaultLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/index.md) | Gets the login accounts that currently have sessions to this vault. | `admin` `session` `idempotent` |
| [GetWindowsGroupMembersInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupMembersInVault/index.md) | Lists the users and groups that are members of a Windows group. | `admin` `session` `idempotent` |
| [GetWindowsGroupsInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault/index.md) | Lists Windows groups of the server's domains, for importing users by group. | `admin` `session` `idempotent` |
| [ModifyVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin/index.md) | Changes the server roles, password, full name, email address or license type of a vault login. | `admin` `session` `idempotent` |
| [ModifyVaultLoginEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/index.md) | Replaces the data of a vault login, optionally including its account name. | `admin` `session` |
| [RemoveVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/RemoveVaultLogin/index.md) | Removes a login account from the vault. | `admin` `session` |
| [ResetVaultLoginPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword/index.md) | Sets a new password for a vault login, authorized by a password reset link. | `admin` `session` |
| [SetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash/index.md) | Sets the password of a vault login from a password hash. | `admin` `session` `idempotent` |

---

# IRPCVaultLoginsAdmin.AddVaultLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin/

Badges: `Administration API / specialized` `admin` `session`

Adds a login account to the vault.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-vault-login`
- **Request:** [`AddVaultLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin/index.md#request)
- **Response:** [`AddVaultLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/AddVaultLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users` (see the service overview for servers where vault
  logins are read-only for vault administrators).
- A vault login cannot be a system administrator: `login.options.system_administrator` fails
  the call.
- The license type is checked against the server's licenses.
- The login does not give access to the vault by itself: add a user account for it with
  [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md).

<a id="request"></a>

## Request: AddVaultLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `login` | [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The new login. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `login.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `login.domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `login.user_name` | `string` | User name. Cannot be unset. |
| `login.options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `login.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `login.options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `login.options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `login.options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `login.full_name` | `string` | The full name of the user. May be unset. |
| `login.email_address` | `string` | The email address of the user. May be unset. |
| `login.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `login.credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `login.client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `login.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |
| `password_hash` | `string` | Legacy field. Leave empty and use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The encrypted password hash, for an M-Files login. |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |

<a id="response"></a>

## Response: AddVaultLoginResponse

No fields.

<a id="related"></a>

## Related methods

- [IRPCUsersAdmin.AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md): Adds a user account to the vault, or brings back a removed one.

---

# IRPCVaultLoginsAdmin.CreateVaultLoginPasswordResetRequest

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest/

Badges: `Administration API / specialized` `admin` `session`

Creates a password reset link for an M-Files login of the vault, and optionally emails it to the
login's email address.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-vault-login-password-reset-request`
- **Request:** [`CreateVaultLoginPasswordResetRequestRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest/index.md#request)
- **Response:** [`CreateVaultLoginPasswordResetRequestResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session; no vault rights are needed to request a reset. Only callers with the
  vault right `manage_users` get the link in `password_reset_url`; for others it is empty and the
  link reaches the user only by email.
- The login is found by `account_name`, or by `account_email_address` when the name is empty
  (the address must match exactly one login). It must be an M-Files login with an email
  address and without the system administrator role; otherwise the request fails.
- `site_url` is required. Repeated requests for the same login in a short time fail. The link
  expires after 7 days by default. The server can be configured to disable password resets.
- Complete the reset with
  [ResetVaultLoginPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword/index.md).

<a id="request"></a>

## Request: CreateVaultLoginPasswordResetRequestRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name of the login, or empty to find it by email address. |
| `account_email_address` | `string` | The email address of the login; used when `account_name` is empty. |
| `site_url` | `string` | The web address the reset link is based on. |
| `send_email` | `bool` | True to email the link to the login's email address. |

<a id="response"></a>

## Response: CreateVaultLoginPasswordResetRequestResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `password_reset_url` | `string` | The reset link; empty unless the caller has the vault right `manage_users`. |

<a id="related"></a>

## Related methods

- [ResetVaultLoginPassword](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword/index.md): Sets a new password for a vault login, authorized by a password reset link.

---

# IRPCVaultLoginsAdmin.ForceLogoutVaultLoginSessions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions/

Badges: `Administration API / specialized` `admin` `session`

Logs out all sessions of the given login accounts in this vault.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/force-logout-vault-login-sessions`
- **Request:** [`ForceLogoutVaultLoginSessionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions/index.md#request)
- **Response:** [`ForceLogoutVaultLoginSessionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Ends the sessions immediately; their clients must log in again. Only sessions to the caller's
  vault are affected.
- Requires the vault right `manage_users`. Find logged-in accounts with
  [GetVaultLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/index.md).

<a id="request"></a>

## Request: ForceLogoutVaultLoginSessionsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_names[]` | repeated `string` | The account names of the logins whose sessions to end. |

<a id="response"></a>

## Response: ForceLogoutVaultLoginSessionsResponse

No fields.

<a id="related"></a>

## Related methods

- [GetVaultLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/index.md): Gets the login accounts that currently have sessions to this vault.

---

# IRPCVaultLoginsAdmin.GetAllDomainsInVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetAllDomainsInVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the domains whose accounts can be imported: the server's own domain and the domains it
can reach.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetAllDomainsInVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-all-domains-in-vault`
- **Request:** [`GetAllDomainsInVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetAllDomainsInVault/index.md#request)
- **Response:** [`GetAllDomainsInVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetAllDomainsInVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Includes the domains of the vault's default user
  synchronization plugin. Returns no directory domains when the server computer is not in a
  domain.

<a id="request"></a>

## Request: GetAllDomainsInVaultRequest

No fields.

<a id="response"></a>

## Response: GetAllDomainsInVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domains[]` | repeated `string` | Domain names. |

---

# IRPCVaultLoginsAdmin.GetFullNameAndEmailInVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetFullNameAndEmailInVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Looks up the full name and email address of a Windows account in the directory.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetFullNameAndEmailInVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-full-name-and-email-in-vault`
- **Request:** [`GetFullNameAndEmailInVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetFullNameAndEmailInVault/index.md#request)
- **Response:** [`GetFullNameAndEmailInVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetFullNameAndEmailInVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Reads the vault's default user synchronization plugin
  if it synchronizes the account's domain, otherwise the domain directory. Used to prefill a new
  login account.
- An empty account name fails with "The parameter is incorrect.".

<a id="request"></a>

## Request: GetFullNameAndEmailInVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The Windows account name, `DOMAIN\user`. |

<a id="response"></a>

## Response: GetFullNameAndEmailInVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `full_name` | `string` | The full name from the directory. |
| `email` | `string` | The email address from the directory. |

---

# IRPCVaultLoginsAdmin.GetOrganizationalUnitsForDomainInVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetOrganizationalUnitsForDomainInVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the organizational units of a domain.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetOrganizationalUnitsForDomainInVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-organizational-units-for-domain-in-vault`
- **Request:** [`GetOrganizationalUnitsForDomainInVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetOrganizationalUnitsForDomainInVault/index.md#request)
- **Response:** [`GetOrganizationalUnitsForDomainInVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetOrganizationalUnitsForDomainInVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Use the result to narrow
  [GetWindowsGroupsInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault/index.md).

<a id="request"></a>

## Request: GetOrganizationalUnitsForDomainInVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domain` | `string` | The domain name in NT format, for example `CONTOSO`. |

<a id="response"></a>

## Response: GetOrganizationalUnitsForDomainInVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `ous[]` | repeated [`DirectoryItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DirectoryItem/index.md) | The organizational units. See [DirectoryItem](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DirectoryItem/index.md). |
| `ous[].distinguished_name` | `string` | The distinguished name of the directory item, e.g. "CN=gr01,OU=orgunit,DC=domain,DC=com" |
| `ous[].display_name` | `string` | Name of the directory object as displayed in user interface. |

<a id="related"></a>

## Related methods

- [GetWindowsGroupsInVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault/index.md): Lists Windows groups of the server's domains, for importing users by group.

---

# IRPCVaultLoginsAdmin.GetVaultLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogin/

Badges: `Administration API / specialized` `admin` `session`

Gets one vault login by account name.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetVaultLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-login`
- **Request:** [`GetVaultLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogin/index.md#request)
- **Response:** [`GetVaultLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any user may read the caller's own login (the name is compared case-insensitively); other
  logins require the vault right `manage_users`. An unknown account fails with "Not found.".

<a id="request"></a>

## Request: GetVaultLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name of the login. |

<a id="response"></a>

## Response: GetVaultLoginResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `plogin` | [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The login. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `plogin.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `plogin.domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `plogin.user_name` | `string` | User name. Cannot be unset. |
| `plogin.options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `plogin.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `plogin.options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `plogin.options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `plogin.options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `plogin.full_name` | `string` | The full name of the user. May be unset. |
| `plogin.email_address` | `string` | The email address of the user. May be unset. |
| `plogin.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `plogin.credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `plogin.client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `plogin.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |

<a id="related"></a>

## Related methods

- [GetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash/index.md): Reads the password hash of a vault login, encrypted with a public key that the caller supplies.

---

# IRPCVaultLoginsAdmin.GetVaultLoginPasswordHash

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Reads the password hash of a vault login, encrypted with a public key that the caller supplies.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-login-password-hash`
- **Request:** [`GetVaultLoginPasswordHashRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash/index.md#request)
- **Response:** [`GetVaultLoginPasswordHashResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. The hash can be stored on another login with
  [SetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash/index.md)
  without anyone knowing the password.
- Encryption is required: `PASSWORD_ENCRYPTION_UNENCRYPTED` fails with "The parameter is
  incorrect.".

<a id="request"></a>

## Request: GetVaultLoginPasswordHashRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `password_encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | How the hash is encrypted for transit. Must not be `PASSWORD_ENCRYPTION_UNENCRYPTED`. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
| `public_key` | `bytes` | The public key the server encrypts the hash with. |
| `account_name` | `string` | The account name of the login. |

<a id="response"></a>

## Response: GetVaultLoginPasswordHashResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `password_hash` | `string` | Legacy copy of the hash. Use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The encrypted password hash with its algorithm and salt. |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |

<a id="related"></a>

## Related methods

- [SetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash/index.md): Sets the password of a vault login from a password hash.
- [GetVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogin/index.md): Gets one vault login by account name.

---

# IRPCVaultLoginsAdmin.GetVaultLogins

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogins/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all login accounts stored in the vault.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetVaultLogins`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-logins`
- **Request:** [`GetVaultLoginsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogins/index.md#request)
- **Response:** [`GetVaultLoginsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogins/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Returns the vault's own logins only, not server
  logins. The order is not specified.

<a id="request"></a>

## Request: GetVaultLoginsRequest

No fields.

<a id="response"></a>

## Response: GetVaultLoginsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The vault logins. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `values[].account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `values[].domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `values[].user_name` | `string` | User name. Cannot be unset. |
| `values[].options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `values[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `values[].options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `values[].options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `values[].options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `values[].full_name` | `string` | The full name of the user. May be unset. |
| `values[].email_address` | `string` | The email address of the user. May be unset. |
| `values[].license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `values[].credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `values[].client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `values[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |

<a id="related"></a>

## Related methods

- [GetVaultLoginsWithSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/index.md): Gets the login accounts that currently have sessions to this vault.

---

# IRPCVaultLoginsAdmin.GetVaultLoginsWithSessions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the login accounts that currently have sessions to this vault.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-logins-with-sessions`
- **Request:** [`GetVaultLoginsWithSessionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/index.md#request)
- **Response:** [`GetVaultLoginsWithSessionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginsWithSessions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Use with
  [ForceLogoutVaultLoginSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions/index.md).

<a id="request"></a>

## Request: GetVaultLoginsWithSessionsRequest

No fields.

<a id="response"></a>

## Response: GetVaultLoginsWithSessionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The logins with active sessions. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `values[].account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `values[].domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `values[].user_name` | `string` | User name. Cannot be unset. |
| `values[].options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `values[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `values[].options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `values[].options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `values[].options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `values[].full_name` | `string` | The full name of the user. May be unset. |
| `values[].email_address` | `string` | The email address of the user. May be unset. |
| `values[].license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `values[].credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `values[].client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `values[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |

<a id="related"></a>

## Related methods

- [ForceLogoutVaultLoginSessions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ForceLogoutVaultLoginSessions/index.md): Logs out all sessions of the given login accounts in this vault.
- [GetVaultLogins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLogins/index.md): Gets all login accounts stored in the vault.

---

# IRPCVaultLoginsAdmin.GetWindowsGroupMembersInVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupMembersInVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists the users and groups that are members of a Windows group.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupMembersInVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-windows-group-members-in-vault`
- **Request:** [`GetWindowsGroupMembersInVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupMembersInVault/index.md#request)
- **Response:** [`GetWindowsGroupMembersInVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupMembersInVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Reads the vault's default user synchronization plugin
  if it synchronizes the group's domain, otherwise the domain directory.

<a id="request"></a>

## Request: GetWindowsGroupMembersInVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `group_name` | `string` | The group, for example `DOMAIN\Domain Users`. |
| `egim` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Whether to include only direct members or also members of nested groups. See [ExternalGroupImportMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md). Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |

<a id="response"></a>

## Response: GetWindowsGroupMembersInVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `users[]` | repeated `string` | Member user names, for example `DOMAIN\user`. |
| `groups[]` | repeated `string` | Member group names, for example `DOMAIN\Group 1`. |

---

# IRPCVaultLoginsAdmin.GetWindowsGroupsInVault

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Lists Windows groups of the server's domains, for importing users by group.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-windows-groups-in-vault`
- **Request:** [`GetWindowsGroupsInVaultRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault/index.md#request)
- **Response:** [`GetWindowsGroupsInVaultResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetWindowsGroupsInVault/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Without a domain, local groups of the server computer
  are included (not on a domain controller).
- The number of groups searched is limited; `group_limit_exceeded` tells whether the list was
  cut. Narrow the search with `domain_name` and `organizational_unit_name_dn`.

<a id="request"></a>

## Request: GetWindowsGroupsInVaultRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domain_name` | `string` | The domain to list groups from, or unset for all groups. |
| `organizational_unit_name_dn` | `string` | The distinguished name of an organizational unit to search in, or unset to search the whole domain. |
| `search_sub_items` | `bool` | True to search the organizational units below it too. Used only with `domain_name`. |

<a id="response"></a>

## Response: GetWindowsGroupsInVaultResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `groups[]` | repeated `string` | Group names, for example `DOMAIN\Domain Users`. |
| `group_limit_exceeded` | `bool` | True if more groups exist than were returned. |

---

# IRPCVaultLoginsAdmin.ModifyVaultLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Changes the server roles, password, full name, email address or license type of a vault login.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-vault-login`
- **Request:** [`ModifyVaultLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin/index.md#request)
- **Response:** [`ModifyVaultLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users` (see the service overview for servers where vault
  logins are read-only for vault administrators).
- `srvroles` is always applied; the system administrator role is refused. The password changes
  only with `change_password`, and the name, email and license type only with
  `update_other_fields`. With `update_other_fields`, a login with an `external_id` fails with
  "Access denied" (it is maintained by identity synchronization).
- An unknown account name fails with "Not found".
- `update_client_id` and `client_id` are ignored by this method.
- To rename the login, use
  [ModifyVaultLoginEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/index.md).

<a id="request"></a>

## Request: ModifyVaultLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name of the login to modify. |
| `srvroles` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | The new server roles of the login. `system_administrator` is not allowed. |
| `srvroles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `srvroles.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `srvroles.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `srvroles.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `change_password` | `bool` | True to set the password from `password_info`. |
| `password_hash` | `string` | Legacy field. Leave empty and use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The new encrypted password hash. Used only with `change_password`. |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
| `update_other_fields` | `bool` | True to set `full_name`, `email_address` and `licensetype`. |
| `full_name` | `string` | The full name of the account. |
| `email_address` | `string` | The email address of the account. |
| `licensetype` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | The new license type. Used only with `update_other_fields`. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `update_client_id` | `bool` | Ignored. |
| `client_id` | `string` | Ignored. |

<a id="response"></a>

## Response: ModifyVaultLoginResponse

No fields.

<a id="related"></a>

## Related methods

- [ModifyVaultLoginEx](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/index.md): Replaces the data of a vault login, optionally including its account name.

---

# IRPCVaultLoginsAdmin.ModifyVaultLoginEx

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/

Badges: `Administration API / specialized` `admin` `session`

Replaces the data of a vault login, optionally including its account name.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-vault-login-ex`
- **Request:** [`ModifyVaultLoginExRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/index.md#request)
- **Response:** [`ModifyVaultLoginExResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLoginEx/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users` (see the service overview for servers where vault
  logins are read-only for vault administrators). The system administrator role is refused.
- If `login` gives a different account name (domain or user name), `allow_changing_username`
  must be true; otherwise the call fails with "Access denied". The new name must not exist yet.
  The user account that refers to the login is updated to the new name. Logins with an
  `external_id` cannot be renamed.
- An unknown `account_name` fails with "Not found".

<a id="request"></a>

## Request: ModifyVaultLoginExRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The current account name of the login. |
| `allow_changing_username` | `bool` | True to allow renaming the login; the user account that refers to it is updated too. |
| `login` | [`Login`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) | The new data of the login. See [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md). |
| `login.account_type` | [`AccountType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AccountType/index.md) | Account type (e.g. M-Files or Windows). Values: `ACCOUNT_TYPE_UNINITIALIZED` (0), `ACCOUNT_TYPE_MFILES` (1), `ACCOUNT_TYPE_WINDOWS` (2). |
| `login.domain_name` | `string` | Domain name, if acctype is eAccountTypeWindows. Otherwise unset. |
| `login.user_name` | `string` | User name. Cannot be unset. |
| `login.options` | [`SRVROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SRVROLES/index.md) | Bitmask of the server roles of the login. |
| `login.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `login.options.system_administrator` | `bool` | System administrator (can perform any operation on the server). [ name( "vaultCreator" ) ] const SRVROLES SRVROLE_VAULT_CREATOR		= ( 1 << 1 );  //!< Can create, modify and delete vaults. Can also restore vaults. [ name( "backupOperator" ) ] const SRVROLES SRVROLE_BACKUP_OPERATOR		= ( 1 << 2 );  //!< Can back up vaults. |
| `login.options.can_log_in` | `bool` | Can log in. A login that does not have this role is disabled and cannot log in even if the login has the sysadmin role. |
| `login.options.invalid_password` | `bool` | This special role indicates that the M-Files login does not yet have a valid password. MFAdmin uses this flag to force the user to define the password. |
| `login.full_name` | `string` | The full name of the user. May be unset. |
| `login.email_address` | `string` | The email address of the user. May be unset. |
| `login.license_type` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | License type. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `login.credential_type` | [`CredentialType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.CredentialType/index.md) | Credential type. Values: `CREDENTIAL_TYPE_USER` (0), `CREDENTIAL_TYPE_TECHNICAL` (1). |
| `login.client_id` | `string` | Client ID, if credentialtype is eCredentialTypeTechnical. Otherwise unset. |
| `login.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). |
| `update_client_id` | `bool` | Ignored by current servers. |

<a id="response"></a>

## Response: ModifyVaultLoginExResponse

No fields.

<a id="related"></a>

## Related methods

- [ModifyVaultLogin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ModifyVaultLogin/index.md): Changes the server roles, password, full name, email address or license type of a vault login.

---

# IRPCVaultLoginsAdmin.RemoveVaultLogin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/RemoveVaultLogin/

Badges: `Administration API / specialized` `admin` `session`

Removes a login account from the vault.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/RemoveVaultLogin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-vault-login`
- **Request:** [`RemoveVaultLoginRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/RemoveVaultLogin/index.md#request)
- **Response:** [`RemoveVaultLoginResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/RemoveVaultLogin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Deletes the login; it can no longer authenticate to this vault. The user account that refers
  to it stays, with its `external_id` cleared; remove or disable it separately with
  [IRPCUsersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md).
- Requires the vault right `manage_users` (see the service overview for servers where vault
  logins are read-only for vault administrators).
- An unknown account name fails with "Not found.". A login with an `external_id` fails with
  "Access denied" ("... should be changed via Manage").

<a id="request"></a>

## Request: RemoveVaultLoginRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name of the login: the user name of an M-Files login, or `DOMAIN\user` of a Windows login. |

<a id="response"></a>

## Response: RemoveVaultLoginResponse

No fields.

---

# IRPCVaultLoginsAdmin.ResetVaultLoginPassword

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword/

Badges: `Administration API / specialized` `admin` `session`

Sets a new password for a vault login, authorized by a password reset link.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-vault-login-password`
- **Request:** [`ResetVaultLoginPasswordRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword/index.md#request)
- **Response:** [`ResetVaultLoginPasswordResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/ResetVaultLoginPassword/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session but no vault rights: `expiration_time` and `reset_password_hash`
  from the link created by
  [CreateVaultLoginPasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest/index.md)
  authorize the change. An expired or invalid link fails.
- The new password must be sent as an encrypted hash: with a `new_password_hash`, an
  unencrypted `password_encryption` or an undefined `password_hash_algorithm_new` fails with
  "The parameter is incorrect.".

<a id="request"></a>

## Request: ResetVaultLoginPasswordRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name from the reset link. |
| `expiration_time` | `string` | The expiration time from the reset link. |
| `reset_password_hash` | `string` | The hash from the reset link. |
| `new_password_hash` | `string` | The encrypted hash of the new password. |
| `password_encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | How `new_password_hash` is encrypted. Must not be `PASSWORD_ENCRYPTION_UNENCRYPTED`. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |
| `password_hash_algorithm_new` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | The algorithm the new password was hashed with. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `new_password_salt` | `string` | The salt used in hashing the new password. |

<a id="response"></a>

## Response: ResetVaultLoginPasswordResponse

No fields.

<a id="related"></a>

## Related methods

- [CreateVaultLoginPasswordResetRequest](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/CreateVaultLoginPasswordResetRequest/index.md): Creates a password reset link for an M-Files login of the vault, and optionally emails it to the login's email address.

---

# IRPCVaultLoginsAdmin.SetVaultLoginPasswordHash

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Sets the password of a vault login from a password hash.

- **Service:** [Vault login accounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) `MFiles.IRPCVaultLoginsAdmin`
- **gRPC method:** `/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-vault-login-password-hash`
- **Request:** [`SetVaultLoginPasswordHashRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash/index.md#request)
- **Response:** [`SetVaultLoginPasswordHashResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/SetVaultLoginPasswordHash/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. An unknown account fails with "Not found.". Only
  M-Files logins have a password; Windows logins authenticate against Windows.

<a id="request"></a>

## Request: SetVaultLoginPasswordHashRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The account name of the login. |
| `password_hash` | `string` | Legacy field. Leave empty and use `password_info`. |
| `password_info` | [`PasswordInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PasswordInfo/index.md) | The new password hash, for example as read with [GetVaultLoginPasswordHash](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/GetVaultLoginPasswordHash/index.md). |
| `password_info.hash` | `string` | Password hash. |
| `password_info.hash_algorithm` | [`PasswordHashAlgorithm`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordHashAlgorithm/index.md) | Password hash algorithm. Values: `PASSWORD_HASH_ALGORITHM_MD5` (0), `PASSWORD_HASH_ALGORITHM_UNDEFINED` (1), `PASSWORD_HASH_ALGORITHM_PBKDF2_WITH_SHA512_AND100000_ITERS` (2). |
| `password_info.salt` | `string` | Password salt. |
| `password_info.encryption` | [`PasswordEncryption`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.PasswordEncryption/index.md) | Encryption algorithm used to protect the password hash. Values: `PASSWORD_ENCRYPTION_RC4` (0), `PASSWORD_ENCRYPTION_UNENCRYPTED` (1), `PASSWORD_ENCRYPTION_AES256` (2). |

<a id="response"></a>

## Response: SetVaultLoginPasswordHashResponse

No fields.

---

# Users (IRPCUsersAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/

Adds, reads, modifies and removes the user accounts of a vault: who may use the vault, with
which vault roles.

Use this interface to add, modify and delete user accounts in a vault.

A user account is always associated with a login. The login defines
the authentication type and password (if not a Windows login). The
user account in a vault just grants a login access to that vault
and specifies the vault-level roles of the user. The user account
has an ID that remains constant and is used to identify the user in
the database (such as 'Last modified by' entry of document). The
user account can be associated with a different login without changing
the user ID in the vault.

Use the IRPCLoginsAdmin and/or IRPCVaultLoginsAdmin interface to manage logins.

- **gRPC service:** `MFiles.IRPCUsersAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 11
- **Proto file:** [`mfiles/IRPCUsersAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCUsersAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service for the Users node of a vault; administration scripts can use it
to provision users. All methods need a vault session whose user has the vault right
`manage_users` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); the write methods also need
`license_allows_modifications`. The vault role full control (and a system administrator's
`full_control_of_vaults`) grants both.

**Login accounts and user accounts.** M-Files separates *who can authenticate* from *who may use
a vault*:

| Account | Stored in | Managed with | What it holds |
| --- | --- | --- | --- |
| Server login account | The server | [IRPCLoginsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLoginsAdmin/index.md) | [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md): account type (M-Files or Windows), user name, password, server roles, license type, full name, email. One login can be used in every vault of the server. |
| Vault login account | One vault | [IRPCVaultLoginsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultLoginsAdmin/index.md) | The same [Login](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Login/index.md) message, valid for that vault only. Exists only on servers with vault login accounts enabled, such as M-Files Cloud. |
| User account | One vault | This service | [UserAccount](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md): the vault user ID, the login it belongs to (`login_name`) and the vault roles. |

- A login authenticates; a user account grants that login access to one vault. A login without a
  user account in the vault cannot open the vault.
- `UserAccount.login_name` is the login's account name: the user name of an M-Files login
  (`MikeT`) or the down-level logon name of a Windows login (domain and user name separated by a
  backslash).
- The user ID never changes. Objects refer to it (Created by, Last modified by, permissions), so
  pointing a user account to another login keeps all references.
- Managing server login accounts needs the system administrator server role (server right
  `manage_logins`); managing user accounts and vault login accounts needs only the vault right
  `manage_users`.

**Methods by task:**

- **Read:** [GetUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUsers/index.md),
  [GetUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md),
  [SearchForUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/SearchForUser/index.md) (by login name).
- **Add or bring back:** [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) (preferred),
  [AddOrUndeleteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md),
  [UndeleteUserByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md).
- **Change and remove:** [ModifyUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/ModifyUser/index.md),
  [RemoveUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/RemoveUser/index.md).
- **Follow changes:** [GetChangedUserAccounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md).

Typical provisioning: make sure the login exists (server or vault login), then
[AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) with `login_name` set to the login's account
name, then add the user to groups with
[AddMemberToUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md).

Users who lack `manage_users` read users and groups through
[IRPCVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md), for example
[GetUsersAndUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUsersAndUserGroups/index.md) and
[GetUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md).

**Accounts with an External ID.** `UserAccount.external_id` links the account to an identity in
an external system such as Microsoft Entra; identity synchronization (M-Files Manage) maintains
it. These methods cannot change it, and removing such an account can fail with "Access denied"
("... should be deleted via Manage").

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddOrUndeleteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md) | Adds a user account, or brings back a removed one with the same login name. | `admin` `session` |
| [AddOrUndeleteUserViaADSync](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUserViaADSync/index.md) | Adds a user account during a directory import; brings back a removed account only when the vault allows that. | `internal: not for applications` `admin` `session` |
| [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) | Adds a user account to the vault, or brings back a removed one. | `admin` `session` |
| [GetChangedUserAccounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md) | Gets the user accounts that were added, changed or removed after a version token. | `admin` `session` |
| [GetUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md) | Gets one user account by ID. | `admin` `session` |
| [GetUsers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUsers/index.md) | Gets all user accounts of the vault. | `admin` `session` `idempotent` |
| [IsVaultReadyForM365StoragePermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/IsVaultReadyForM365StoragePermissions/index.md) | Tells whether the vault meets the user identity precondition for projecting M-Files permissions to Microsoft 365 storage. | `internal: not for applications` `admin` `session` `idempotent` |
| [ModifyUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/ModifyUser/index.md) | Replaces the data of an existing user account. | `admin` `session` `idempotent` |
| [RemoveUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/RemoveUser/index.md) | Removes a user account from the vault. | `admin` `session` |
| [SearchForUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/SearchForUser/index.md) | Finds the user account of a login name. | `admin` `session` |
| [UndeleteUserByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md) | Brings back a removed user account, identified by its GUID in the Users value list. | `admin` `session` |

---

# IRPCUsersAdmin.AddOrUndeleteUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/

Badges: `Administration API / specialized` `admin` `session`

Adds a user account, or brings back a removed one with the same login name.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/AddOrUndeleteUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-or-undelete-user`
- **Request:** [`AddOrUndeleteUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md#request)
- **Response:** [`AddOrUndeleteUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Same as [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) with `addition_mode`
  `USER_ACCOUNT_ADDITION_MODE_UNDELETE_OR_ADD`, but without `tasks_before_login` in the
  response. Prefer [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md).

<a id="request"></a>

## Request: AddOrUndeleteUserRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `user_account` | [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The new account. `login_name` is required; `id` is ignored. A removed user with the same login name is brought back with its old ID. |
| `user_account.id` | `int32` | The ID of the user account. |
| `user_account.login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `user_account.vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `user_account.vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `user_account.vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `user_account.vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `user_account.vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `user_account.vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `user_account.vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `user_account.vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `user_account.vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `user_account.vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `user_account.vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `user_account.vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `user_account.vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `user_account.vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `user_account.vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `user_account.vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `user_account.vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `user_account.vault_roles.anonymous` | `bool` | Anonymous role. |
| `user_account.vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `user_account.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `user_account.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `user_account.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `user_account.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `user_account.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `user_account.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `user_account.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `user_account.user_language` | `int32` | The vault language of the user. |
| `user_account.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |

<a id="response"></a>

## Response: AddOrUndeleteUserResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new or restored user account. |

<a id="related"></a>

## Related methods

- [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md): Adds a user account to the vault, or brings back a removed one.
- [AddOrUndeleteUserViaADSync](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUserViaADSync/index.md): Adds a user account during a directory import; brings back a removed account only when the vault allows that.

---

# IRPCUsersAdmin.AddOrUndeleteUserViaADSync

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUserViaADSync/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session`

Adds a user account during a directory import; brings back a removed account only when the
vault allows that.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/AddOrUndeleteUserViaADSync`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-or-undelete-user-via-adsync`
- **Request:** [`AddOrUndeleteUserViaADSyncRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUserViaADSync/index.md#request)
- **Response:** [`AddOrUndeleteUserViaADSyncResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUserViaADSync/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **For M-Files components only.** M-Files Admin calls it when it imports users from a
  directory. Applications should not call it; use
  [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md).
- Works like [AddOrUndeleteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md), except that a
  removed user is brought back only if the vault is configured to allow undeleting users in
  directory synchronization; otherwise a new account is always added.
- Requires the vault rights `manage_users` and `license_allows_modifications`.

<a id="request"></a>

## Request: AddOrUndeleteUserViaADSyncRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `user_account` | [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The new account. `login_name` is required; `id` is ignored. |
| `user_account.id` | `int32` | The ID of the user account. |
| `user_account.login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `user_account.vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `user_account.vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `user_account.vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `user_account.vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `user_account.vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `user_account.vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `user_account.vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `user_account.vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `user_account.vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `user_account.vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `user_account.vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `user_account.vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `user_account.vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `user_account.vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `user_account.vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `user_account.vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `user_account.vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `user_account.vault_roles.anonymous` | `bool` | Anonymous role. |
| `user_account.vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `user_account.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `user_account.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `user_account.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `user_account.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `user_account.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `user_account.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `user_account.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `user_account.user_language` | `int32` | The vault language of the user. |
| `user_account.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |

<a id="response"></a>

## Response: AddOrUndeleteUserViaADSyncResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new or restored user account. |

<a id="related"></a>

## Related methods

- [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md): Adds a user account to the vault, or brings back a removed one.
- [AddOrUndeleteUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddOrUndeleteUser/index.md): Adds a user account, or brings back a removed one with the same login name.

---

# IRPCUsersAdmin.AddUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/

Badges: `Administration API / specialized` `admin` `session`

Adds a user account to the vault, or brings back a removed one.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/AddUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-user`
- **Request:** [`AddUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md#request)
- **Response:** [`AddUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`. A new account
  with the `full_control` role also requires `change_full_control_role`.
- `login_name` must not be empty ("The parameter is incorrect.") and must not belong to another
  user account (compared case-insensitively; "already exists").
- The role `run_code_on_server` cannot be granted here; the server removes it.
- `external_id` may be left empty; the server copies it from the login. A value that differs
  from the login's fails with "Access denied.".
- `addition_mode` decides what happens when a removed user with the same login name exists:
  `USER_ACCOUNT_ADDITION_MODE_UNDELETE_OR_ADD` brings it back with its old user ID, so old
  references point to it again; `USER_ACCOUNT_ADDITION_MODE_ALWAYS_ADD` adds a new user ID.
- The response lists background tasks that prepare the new user's permissions. Until they
  complete, the user's login to the vault can be refused.

<a id="request"></a>

## Request: AddUserRequest

A structure that specifies an add user request.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `user_account` | [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The new account: `login_name`, `vault_roles`, and optionally `acl` and `user_language`. `id` is ignored. |
| `user_account.id` | `int32` | The ID of the user account. |
| `user_account.login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `user_account.vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `user_account.vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `user_account.vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `user_account.vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `user_account.vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `user_account.vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `user_account.vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `user_account.vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `user_account.vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `user_account.vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `user_account.vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `user_account.vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `user_account.vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `user_account.vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `user_account.vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `user_account.vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `user_account.vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `user_account.vault_roles.anonymous` | `bool` | Anonymous role. |
| `user_account.vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `user_account.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `user_account.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `user_account.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `user_account.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `user_account.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `user_account.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `user_account.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `user_account.user_language` | `int32` | The vault language of the user. |
| `user_account.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |
| `addition_mode` | [`UserAccountAdditionMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserAccountAdditionMode/index.md) | Whether a removed account with the same login name is brought back. See [UserAccountAdditionMode](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserAccountAdditionMode/index.md). Values: `USER_ACCOUNT_ADDITION_MODE_ALWAYS_ADD` (0), `USER_ACCOUNT_ADDITION_MODE_UNDELETE_OR_ADD` (1), `USER_ACCOUNT_ADDITION_MODE_ONLY_UNDELETE` (2). |

<a id="response"></a>

## Response: AddUserResponse

A structure that specifies an add user response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new or restored user account. |
| `tasks_before_login[]` | repeated [`AsyncTaskID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTaskID/index.md) | Background tasks that must complete before the user can log in to the vault. |
| `tasks_before_login[].id` | `int64` | Task ID. |
| `tasks_before_login[].type` | `string` | Task type name. |
| `tasks_before_login[].definition` | `string` | The display string of the task definition. |

---

# IRPCUsersAdmin.GetChangedUserAccounts

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/

Badges: `Administration API / specialized` `admin` `session`

Gets the user accounts that were added, changed or removed after a version token.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/GetChangedUserAccounts`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-changed-user-accounts`
- **Request:** [`GetChangedUserAccountsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md#request)
- **Response:** [`GetChangedUserAccountsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`.
- Available only for vaults on Microsoft SQL Server; other vaults fail with "Not implemented.".
- Start with `version_token` 0, then send the returned `version_token` in the next call. When
  nothing changed, the response has the same token and empty lists.
- Changes are returned oldest first. With `max_changes`, call again until the lists are empty.

<a id="request"></a>

## Request: GetChangedUserAccountsRequest

Request structure for the GetChangedUserAccounts method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `version_token` | `int64` | The `version_token` of the previous response, or 0 for all changes. |
| `max_changes` | `uint32` | The maximum number of changes to return; 0 for no limit. |

<a id="response"></a>

## Response: GetChangedUserAccountsResponse

Response structure for the GetChangedUserAccounts method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `new_and_modified[]` | repeated [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | Accounts added or changed after `version_token`. |
| `new_and_modified[].id` | `int32` | The ID of the user account. |
| `new_and_modified[].login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `new_and_modified[].vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `new_and_modified[].vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `new_and_modified[].vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `new_and_modified[].vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `new_and_modified[].vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `new_and_modified[].vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `new_and_modified[].vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `new_and_modified[].vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `new_and_modified[].vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `new_and_modified[].vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `new_and_modified[].vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `new_and_modified[].vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `new_and_modified[].vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `new_and_modified[].vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `new_and_modified[].vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `new_and_modified[].vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `new_and_modified[].vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `new_and_modified[].vault_roles.anonymous` | `bool` | Anonymous role. |
| `new_and_modified[].vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `new_and_modified[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `new_and_modified[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `new_and_modified[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `new_and_modified[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `new_and_modified[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `new_and_modified[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `new_and_modified[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `new_and_modified[].user_language` | `int32` | The vault language of the user. |
| `new_and_modified[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |
| `deleted[]` | repeated `int32` | IDs of accounts removed after `version_token`. |
| `version_token` | `int64` | The version of the last returned change; send it in the next call. |

---

# IRPCUsersAdmin.GetUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/

Badges: `Administration API / specialized` `admin` `session`

Gets one user account by ID.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/GetUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user`
- **Request:** [`GetUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md#request)
- **Response:** [`GetUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`.
- A negative ID fails with "The parameter is incorrect."; an unknown ID (including 0) fails
  with "Not found.".

<a id="request"></a>

## Request: GetUserRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `user` | `int32` | The ID of the user account. |

<a id="response"></a>

## Response: GetUserResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `putf8szua` | [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The user account. See [UserAccount](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md). |
| `putf8szua.id` | `int32` | The ID of the user account. |
| `putf8szua.login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `putf8szua.vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `putf8szua.vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `putf8szua.vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `putf8szua.vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `putf8szua.vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `putf8szua.vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `putf8szua.vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `putf8szua.vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `putf8szua.vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `putf8szua.vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `putf8szua.vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `putf8szua.vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `putf8szua.vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `putf8szua.vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `putf8szua.vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `putf8szua.vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `putf8szua.vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `putf8szua.vault_roles.anonymous` | `bool` | Anonymous role. |
| `putf8szua.vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `putf8szua.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `putf8szua.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `putf8szua.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `putf8szua.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `putf8szua.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `putf8szua.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `putf8szua.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `putf8szua.user_language` | `int32` | The vault language of the user. |
| `putf8szua.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |

---

# IRPCUsersAdmin.GetUsers

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUsers/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all user accounts of the vault.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/GetUsers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-users`
- **Request:** [`GetUsersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUsers/index.md#request)
- **Response:** [`GetUsersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUsers/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with the vault right `manage_users`; otherwise fails with "Access
  denied.".
- Returns existing accounts only; removed users are not included. The order is not specified.

<a id="request"></a>

## Request: GetUsersRequest

No fields.

<a id="response"></a>

## Response: GetUsersResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `results[]` | repeated [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | All user accounts. See [UserAccount](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md). |
| `results[].id` | `int32` | The ID of the user account. |
| `results[].login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `results[].vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `results[].vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `results[].vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `results[].vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `results[].vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `results[].vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `results[].vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `results[].vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `results[].vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `results[].vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `results[].vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `results[].vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `results[].vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `results[].vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `results[].vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `results[].vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `results[].vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `results[].vault_roles.anonymous` | `bool` | Anonymous role. |
| `results[].vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `results[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `results[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `results[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `results[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `results[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `results[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `results[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `results[].user_language` | `int32` | The vault language of the user. |
| `results[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |

---

# IRPCUsersAdmin.IsVaultReadyForM365StoragePermissions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/IsVaultReadyForM365StoragePermissions/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Tells whether the vault meets the user identity precondition for projecting M-Files permissions
to Microsoft 365 storage.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/IsVaultReadyForM365StoragePermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/is-vault-ready-for-m365-storage-permissions`
- **Request:** [`IsVaultReadyForM365StoragePermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/IsVaultReadyForM365StoragePermissions/index.md#request)
- **Response:** [`IsVaultReadyForM365StoragePermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/IsVaultReadyForM365StoragePermissions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **For M-Files components only.** M-Files Admin calls it before it saves the setting.
  Applications should not call it.
- Not available in this version: the server fails it with "Not implemented.".
- Requires the vault right `manage_users`. True when at least one user account with the
  `can_log_in` role has a Microsoft Entra object ID (a GUID) as `external_id`.

<a id="request"></a>

## Request: IsVaultReadyForM365StoragePermissionsRequest

No fields.

<a id="response"></a>

## Response: IsVaultReadyForM365StoragePermissionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `is_vault_ready` | `bool` | True if the vault meets the precondition. |

---

# IRPCUsersAdmin.ModifyUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/ModifyUser/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Replaces the data of an existing user account.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/ModifyUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-user`
- **Request:** [`ModifyUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/ModifyUser/index.md#request)
- **Response:** [`ModifyUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/ModifyUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`. Adding or
  removing the `full_control` role also requires `change_full_control_role`.
- Send the complete account: read it with [GetUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md),
  change what you need and send it back.
- Changing `login_name` points the user account to another login and keeps the user ID. The new
  name must not belong to another user account (compared case-insensitively). Vaults that are
  21 CFR Part 11 compliant can be configured to refuse login name changes.
- `external_id` cannot be changed here ("Access denied."); leave it as read.
- The role `run_code_on_server` cannot be set through this service: the server removes it from
  the roles you send.
- Removing `can_log_in` logs the user's sessions out of the vault.

<a id="request"></a>

## Request: ModifyUserRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `user_account` | [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The complete new data of the account; `id` identifies the account to modify. |
| `user_account.id` | `int32` | The ID of the user account. |
| `user_account.login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `user_account.vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `user_account.vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `user_account.vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `user_account.vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `user_account.vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `user_account.vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `user_account.vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `user_account.vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `user_account.vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `user_account.vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `user_account.vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `user_account.vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `user_account.vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `user_account.vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `user_account.vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `user_account.vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `user_account.vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `user_account.vault_roles.anonymous` | `bool` | Anonymous role. |
| `user_account.vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `user_account.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `user_account.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `user_account.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `user_account.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `user_account.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `user_account.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `user_account.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `user_account.user_language` | `int32` | The vault language of the user. |
| `user_account.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |

<a id="response"></a>

## Response: ModifyUserResponse

No fields.

<a id="related"></a>

## Related methods

- [GetUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetUser/index.md): Gets one user account by ID.

---

# IRPCUsersAdmin.RemoveUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/RemoveUser/

Badges: `Administration API / specialized` `admin` `session`

Removes a user account from the vault.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/RemoveUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-user`
- **Request:** [`RemoveUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/RemoveUser/index.md#request)
- **Response:** [`RemoveUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/RemoveUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Removes the account and its private data: its views, notification rules, event subscriptions
  and group memberships are deleted. Requires the vault rights `manage_users` and
  `license_allows_modifications`; removing an account with the `full_control` role also requires
  `change_full_control_role`.
- The user stays in the Users value list (6) as a deleted item, so objects that refer to the
  user keep the reference. Bring the account back with
  [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md) (`USER_ACCOUNT_ADDITION_MODE_UNDELETE_OR_ADD`)
  or [UndeleteUserByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md); the deleted views
  and rules do not come back.
- The login account is not removed.
- An account with an `external_id` can fail with "Access denied" ("... should be deleted via
  Manage").

<a id="request"></a>

## Request: RemoveUserRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the user account to remove. |

<a id="response"></a>

## Response: RemoveUserResponse

No fields.

<a id="related"></a>

## Related methods

- [AddUser](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/AddUser/index.md): Adds a user account to the vault, or brings back a removed one.
- [UndeleteUserByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md): Brings back a removed user account, identified by its GUID in the Users value list.

---

# IRPCUsersAdmin.SearchForUser

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/SearchForUser/

Badges: `Administration API / specialized` `admin` `session`

Finds the user account of a login name.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/SearchForUser`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/search-for-user`
- **Request:** [`SearchForUserRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/SearchForUser/index.md#request)
- **Response:** [`SearchForUserResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/SearchForUser/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`.
- Matches the whole login name, case-insensitively; there are no wildcards or partial matches.
  Returns an empty list, not an error, when no account matches.

<a id="request"></a>

## Request: SearchForUserRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_name` | `string` | The login name to look for, for example `MikeT` or `DOMAIN\user`. |

<a id="response"></a>

## Response: SearchForUserResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `results[]` | repeated [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The matching user account, or empty. |
| `results[].id` | `int32` | The ID of the user account. |
| `results[].login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `results[].vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `results[].vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `results[].vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `results[].vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `results[].vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `results[].vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `results[].vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `results[].vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `results[].vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `results[].vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `results[].vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `results[].vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `results[].vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `results[].vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `results[].vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `results[].vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `results[].vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `results[].vault_roles.anonymous` | `bool` | Anonymous role. |
| `results[].vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `results[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `results[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `results[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `results[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `results[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `results[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `results[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `results[].user_language` | `int32` | The vault language of the user. |
| `results[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |

---

# IRPCUsersAdmin.UndeleteUserByGUID

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/

Badges: `Administration API / specialized` `admin` `session`

Brings back a removed user account, identified by its GUID in the Users value list.

- **Service:** [Users](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md) `MFiles.IRPCUsersAdmin`
- **gRPC method:** `/MFiles.IRPCUsersAdmin/UndeleteUserByGUID`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/undelete-user-by-guid`
- **Request:** [`UndeleteUserByGUIDRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md#request)
- **Response:** [`UndeleteUserByGUIDResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/UndeleteUserByGUID/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`.
- Never adds a new account. If no removed user has the GUID, the call fails with "Not found"
  (it does not return -1).
- Find the GUID of a removed user among the deleted items of the Users value list (6), for
  example with
  [SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md).

<a id="request"></a>

## Request: UndeleteUserByGUIDRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `account_to_undelete` | `string` | The GUID of the removed user's item in the Users value list (6). |
| `user_account_data` | [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The data to store in the restored account (`login_name`, vault roles, ...). `id` is ignored. |
| `user_account_data.id` | `int32` | The ID of the user account. |
| `user_account_data.login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `user_account_data.vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `user_account_data.vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `user_account_data.vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `user_account_data.vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `user_account_data.vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `user_account_data.vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `user_account_data.vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `user_account_data.vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `user_account_data.vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `user_account_data.vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `user_account_data.vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `user_account_data.vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `user_account_data.vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `user_account_data.vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `user_account_data.vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `user_account_data.vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `user_account_data.vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `user_account_data.vault_roles.anonymous` | `bool` | Anonymous role. |
| `user_account_data.vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `user_account_data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `user_account_data.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `user_account_data.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `user_account_data.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `user_account_data.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `user_account_data.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `user_account_data.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `user_account_data.user_language` | `int32` | The vault language of the user. |
| `user_account_data.external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |

<a id="response"></a>

## Response: UndeleteUserByGUIDResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `account_id` | `int32` | The ID of the restored user account (the user's old ID). |

<a id="related"></a>

## Related methods

- [IRPCValueLists.SearchValueListItemsWithPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/SearchValueListItemsWithPermissions/index.md): Searches the items of one value list or object type by item ID, name, owner, parent or deleted state.

---

# User groups (IRPCUserGroupsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/

Adds, reads, modifies and removes the user groups of a vault and their members.

Use this interface to add, modify and delete user groups in a vault.

A user group consists of members. A member can be a user account
or another user group. A special type of user group is a Windows Group
that refers to an existing Windows local or global group. The
members of a Windows Group are not defined in the vault database
but are instead queried from Windows whenever needed.

- **gRPC service:** `MFiles.IRPCUserGroupsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 12
- **Proto file:** [`mfiles/IRPCUserGroupsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCUserGroupsAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service for the User groups node of a vault and for importing Windows
groups. All methods need a vault session whose user has the vault right `manage_users`
([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); the write methods also need
`license_allows_modifications`.

- **Members.** `UserGroup.user_group.members` lists user account IDs as positive numbers and
  member groups as negative numbers (group 102 is -102). The same convention applies to
  `member_id` of [AddMemberToUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md)
  and [RemoveMemberFromUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/index.md).
- **Built-in groups.** 1 "All internal users" and 2 "All internal and external users" are
  returned with empty `members`: their membership follows from the users' `is_internal_user`
  role. They can be renamed but not given members or removed.
- **External Windows groups** (`is_external_windows_group`) mirror a group of the domain
  directory. [SyncExternalWindowsGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/SyncExternalWindowsGroup/index.md)
  updates their members;
  [GetUserGroupSyncStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus/index.md) reports
  the last synchronization.
- **Group types.** Besides normal groups (`USER_GROUP_TYPE_NORMAL`), a vault can have groups that
  represent users and groups of an external repository.
  [GetUserGroupsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/index.md) returns normal groups
  only; [GetUserContainersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/index.md) returns
  all types.

Methods by task:

- **Read:** [GetUserGroupsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/index.md),
  [GetUserGroupAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin/index.md),
  [GetUserContainersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/index.md),
  [GetChangedUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetChangedUserGroups/index.md).
- **Add, change, remove:** [AddUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddUserGroup/index.md),
  [AddOrUndeleteUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup/index.md),
  [ModifyUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/ModifyUserGroup/index.md),
  [RemoveUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveUserGroup/index.md).
- **Change one membership** without sending the whole group:
  [AddMemberToUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md),
  [RemoveMemberFromUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/index.md).

Users without `manage_users` read groups with
[GetUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetUserGroups/index.md) of
[IRPCVault](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/index.md). Users are managed with
[IRPCUsersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddMemberToUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md) | Adds one user or group to a user group, if it is not a member yet. | `admin` `session` |
| [AddOrUndeleteUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup/index.md) | Adds a user group, or brings back a removed group with the same name. | `admin` `session` |
| [AddUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddUserGroup/index.md) | Adds a user group to the vault. | `admin` `session` |
| [GetChangedUserGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetChangedUserGroups/index.md) | Gets the user groups that were added, changed or removed after a version token. | `admin` `session` |
| [GetUserContainersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/index.md) | Gets all user groups of the vault, including the groups that represent external repository users and groups. | `admin` `session` `idempotent` |
| [GetUserGroupAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin/index.md) | Gets one user group of any type, with its members. | `admin` `session` |
| [GetUserGroupsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/index.md) | Gets all normal user groups of the vault, with their members. | `admin` `session` |
| [GetUserGroupSyncStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus/index.md) | Gets the result of the last synchronization of an external Windows group. | `admin` `session` |
| [ModifyUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/ModifyUserGroup/index.md) | Replaces the data and members of an existing user group. | `admin` `session` `idempotent` |
| [RemoveMemberFromUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/index.md) | Removes one user or group from a user group, if it is a member. | `admin` `session` |
| [RemoveUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveUserGroup/index.md) | Removes a user group from the vault. | `admin` `session` |
| [SyncExternalWindowsGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/SyncExternalWindowsGroup/index.md) | Updates the members of an external Windows group from the domain directory. | `admin` `session` `idempotent` |

---

# IRPCUserGroupsAdmin.AddMemberToUserGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/

Badges: `Administration API / specialized` `admin` `session`

Adds one user or group to a user group, if it is not a member yet.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-member-to-user-group`
- **Request:** [`AddMemberToUserGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md#request)
- **Response:** [`AddMemberToUserGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`.
- Does nothing if the member is already in the group, so the call can be repeated safely.
- The member must suit the group's type; an unknown group fails with "Not found.".

<a id="request"></a>

## Request: AddMemberToUserGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `user_group` | `int32` | The ID of the group to add the member to. |
| `member_id` | `int32` | The user account ID, or the negated ID of a user group (-102 for group 102). |

<a id="response"></a>

## Response: AddMemberToUserGroupResponse

No fields.

---

# IRPCUserGroupsAdmin.AddOrUndeleteUserGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup/

Badges: `Administration API / specialized` `admin` `session`

Adds a user group, or brings back a removed group with the same name.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-or-undelete-user-group`
- **Request:** [`AddOrUndeleteUserGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup/index.md#request)
- **Response:** [`AddOrUndeleteUserGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`.
- If a removed group has the same name, it is restored with its old ID, so permissions that
  refer to it apply again. An existing group with the same name fails with "already exists".
- Fails with "The parameter is incorrect." on servers configured not to refresh the user groups
  list when groups are added through the API.

<a id="request"></a>

## Request: AddOrUndeleteUserGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `usergroup` | [`UserGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md) | The group. `user_group.id` is ignored. |
| `usergroup.user_group` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The basic data of the group. |
| `usergroup.user_group.id` | `int32` | The ID of the user group. |
| `usergroup.user_group.name` | `string` | The name of the group. |
| `usergroup.user_group.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `usergroup.user_group.type` | [`UserGroupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md) | User group type. Values: `USER_GROUP_TYPE_NORMAL` (0), `USER_GROUP_TYPE_REPOSITORY_USER` (1), `USER_GROUP_TYPE_REPOSITORY_GROUP` (2), `USER_GROUP_TYPE_ANY` (-1). |
| `usergroup.is_external_windows_group` | `bool` | Is group imported from Windows domain. |
| `usergroup.synchronize_memberships` | `bool` | Should memberships of this group be synchronized automatically. |
| `usergroup.license_type_for_new_logins` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | Type of the license for logins created automatically. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `usergroup.external_group_name` | `string` | The name for external group. Empty if the group is not external. |
| `usergroup.organizational_unit` | `string` | The organizational unit for filtering the AD group searches. Empty if the group is not external. |
| `usergroup.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `usergroup.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `usergroup.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `usergroup.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `usergroup.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `usergroup.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `usergroup.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `usergroup.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `usergroup.import_mode` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Import mode for external groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |
| `usergroup.external_repository_name` | `string` | External repository name. unset if this group doesn't represent external repository user information. |
| `usergroup.external_repository_subject_id` | `string` | ID in the external repository. unset if this group doesn't represent external repository user information. |
| `add_memebers_as_imported_users` | `bool` | See [AddUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddUserGroup/index.md); leave false. |

<a id="response"></a>

## Response: AddOrUndeleteUserGroupResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new or restored group. |

---

# IRPCUserGroupsAdmin.AddUserGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddUserGroup/

Badges: `Administration API / specialized` `admin` `session`

Adds a user group to the vault.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/AddUserGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-user-group`
- **Request:** [`AddUserGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddUserGroup/index.md#request)
- **Response:** [`AddUserGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddUserGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`.
- The name must be unique among the vault's groups; a duplicate fails with "already exists".
  To bring back a removed group with the same name, use
  [AddOrUndeleteUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup/index.md).
- Members use the sign convention of the service overview (groups negative).

<a id="request"></a>

## Request: AddUserGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `usergroup` | [`UserGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md) | The new group. `user_group.id` is ignored; the server assigns the ID. |
| `usergroup.user_group` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The basic data of the group. |
| `usergroup.user_group.id` | `int32` | The ID of the user group. |
| `usergroup.user_group.name` | `string` | The name of the group. |
| `usergroup.user_group.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `usergroup.user_group.type` | [`UserGroupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md) | User group type. Values: `USER_GROUP_TYPE_NORMAL` (0), `USER_GROUP_TYPE_REPOSITORY_USER` (1), `USER_GROUP_TYPE_REPOSITORY_GROUP` (2), `USER_GROUP_TYPE_ANY` (-1). |
| `usergroup.is_external_windows_group` | `bool` | Is group imported from Windows domain. |
| `usergroup.synchronize_memberships` | `bool` | Should memberships of this group be synchronized automatically. |
| `usergroup.license_type_for_new_logins` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | Type of the license for logins created automatically. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `usergroup.external_group_name` | `string` | The name for external group. Empty if the group is not external. |
| `usergroup.organizational_unit` | `string` | The organizational unit for filtering the AD group searches. Empty if the group is not external. |
| `usergroup.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `usergroup.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `usergroup.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `usergroup.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `usergroup.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `usergroup.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `usergroup.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `usergroup.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `usergroup.import_mode` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Import mode for external groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |
| `usergroup.external_repository_name` | `string` | External repository name. unset if this group doesn't represent external repository user information. |
| `usergroup.external_repository_subject_id` | `string` | ID in the external repository. unset if this group doesn't represent external repository user information. |
| `add_memebers_as_imported_users` | `bool` | True to record the member user accounts as imported through this group. M-Files Admin sets it when it imports a Windows group with its users; leave it false otherwise. |

<a id="response"></a>

## Response: AddUserGroupResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new user group. |

<a id="related"></a>

## Related methods

- [AddOrUndeleteUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddOrUndeleteUserGroup/index.md): Adds a user group, or brings back a removed group with the same name.

---

# IRPCUserGroupsAdmin.GetChangedUserGroups

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetChangedUserGroups/

Badges: `Administration API / specialized` `admin` `session`

Gets the user groups that were added, changed or removed after a version token.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/GetChangedUserGroups`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-changed-user-groups`
- **Request:** [`GetChangedUserGroupsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetChangedUserGroups/index.md#request)
- **Response:** [`GetChangedUserGroupsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetChangedUserGroups/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`.
- Available only for vaults on Microsoft SQL Server; other vaults fail with "Not implemented.".
- Works like [GetChangedUserAccounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md): start
  with `version_token` 0 and send the returned token in the next call. Changes are returned
  oldest first.

<a id="request"></a>

## Request: GetChangedUserGroupsRequest

Request structure for the GetChangedUserGroups method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `version_token` | `int64` | The `version_token` of the previous response, or 0 for all changes. |
| `max_changes` | `uint32` | The maximum number of changes to return; 0 for no limit. |

<a id="response"></a>

## Response: GetChangedUserGroupsResponse

Response structure for the GetChangedUserGroups method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `new_and_modified[]` | repeated [`UserGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md) | Groups added or changed after `version_token`. |
| `new_and_modified[].user_group` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The basic data of the group. |
| `new_and_modified[].user_group.id` | `int32` | The ID of the user group. |
| `new_and_modified[].user_group.name` | `string` | The name of the group. |
| `new_and_modified[].user_group.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `new_and_modified[].user_group.type` | [`UserGroupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md) | User group type. Values: `USER_GROUP_TYPE_NORMAL` (0), `USER_GROUP_TYPE_REPOSITORY_USER` (1), `USER_GROUP_TYPE_REPOSITORY_GROUP` (2), `USER_GROUP_TYPE_ANY` (-1). |
| `new_and_modified[].is_external_windows_group` | `bool` | Is group imported from Windows domain. |
| `new_and_modified[].synchronize_memberships` | `bool` | Should memberships of this group be synchronized automatically. |
| `new_and_modified[].license_type_for_new_logins` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | Type of the license for logins created automatically. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `new_and_modified[].external_group_name` | `string` | The name for external group. Empty if the group is not external. |
| `new_and_modified[].organizational_unit` | `string` | The organizational unit for filtering the AD group searches. Empty if the group is not external. |
| `new_and_modified[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `new_and_modified[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `new_and_modified[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `new_and_modified[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `new_and_modified[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `new_and_modified[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `new_and_modified[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `new_and_modified[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `new_and_modified[].import_mode` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Import mode for external groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |
| `new_and_modified[].external_repository_name` | `string` | External repository name. unset if this group doesn't represent external repository user information. |
| `new_and_modified[].external_repository_subject_id` | `string` | ID in the external repository. unset if this group doesn't represent external repository user information. |
| `deleted[]` | repeated `int32` | IDs of groups removed after `version_token`. |
| `version_token` | `int64` | The version of the last returned change; send it in the next call. |

<a id="related"></a>

## Related methods

- [IRPCUsersAdmin.GetChangedUserAccounts](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUsersAdmin/GetChangedUserAccounts/index.md): Gets the user accounts that were added, changed or removed after a version token.

---

# IRPCUserGroupsAdmin.GetUserContainersAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all user groups of the vault, including the groups that represent external repository
users and groups.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user-containers-admin`
- **Request:** [`GetUserContainersAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/index.md#request)
- **Response:** [`GetUserContainersAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Like
  [GetUserGroupsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/index.md), but returns groups
  of every [UserGroupType](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md).

<a id="request"></a>

## Request: GetUserContainersAdminRequest

No fields.

<a id="response"></a>

## Response: GetUserContainersAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`UserGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md) | The user groups of all types. |
| `values[].user_group` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The basic data of the group. |
| `values[].user_group.id` | `int32` | The ID of the user group. |
| `values[].user_group.name` | `string` | The name of the group. |
| `values[].user_group.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `values[].user_group.type` | [`UserGroupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md) | User group type. Values: `USER_GROUP_TYPE_NORMAL` (0), `USER_GROUP_TYPE_REPOSITORY_USER` (1), `USER_GROUP_TYPE_REPOSITORY_GROUP` (2), `USER_GROUP_TYPE_ANY` (-1). |
| `values[].is_external_windows_group` | `bool` | Is group imported from Windows domain. |
| `values[].synchronize_memberships` | `bool` | Should memberships of this group be synchronized automatically. |
| `values[].license_type_for_new_logins` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | Type of the license for logins created automatically. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `values[].external_group_name` | `string` | The name for external group. Empty if the group is not external. |
| `values[].organizational_unit` | `string` | The organizational unit for filtering the AD group searches. Empty if the group is not external. |
| `values[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `values[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `values[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `values[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `values[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `values[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `values[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `values[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `values[].import_mode` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Import mode for external groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |
| `values[].external_repository_name` | `string` | External repository name. unset if this group doesn't represent external repository user information. |
| `values[].external_repository_subject_id` | `string` | ID in the external repository. unset if this group doesn't represent external repository user information. |

<a id="related"></a>

## Related methods

- [GetUserGroupsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/index.md): Gets all normal user groups of the vault, with their members.

---

# IRPCUserGroupsAdmin.GetUserGroupAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin/

Badges: `Administration API / specialized` `admin` `session`

Gets one user group of any type, with its members.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user-group-admin`
- **Request:** [`GetUserGroupAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin/index.md#request)
- **Response:** [`GetUserGroupAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. An unknown ID fails with "Not found.".

<a id="request"></a>

## Request: GetUserGroupAdminRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `user_group` | `int32` | The ID of the user group. |

<a id="response"></a>

## Response: GetUserGroupAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `usergroup` | [`UserGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md) | The user group. See [UserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md). |
| `usergroup.user_group` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The basic data of the group. |
| `usergroup.user_group.id` | `int32` | The ID of the user group. |
| `usergroup.user_group.name` | `string` | The name of the group. |
| `usergroup.user_group.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `usergroup.user_group.type` | [`UserGroupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md) | User group type. Values: `USER_GROUP_TYPE_NORMAL` (0), `USER_GROUP_TYPE_REPOSITORY_USER` (1), `USER_GROUP_TYPE_REPOSITORY_GROUP` (2), `USER_GROUP_TYPE_ANY` (-1). |
| `usergroup.is_external_windows_group` | `bool` | Is group imported from Windows domain. |
| `usergroup.synchronize_memberships` | `bool` | Should memberships of this group be synchronized automatically. |
| `usergroup.license_type_for_new_logins` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | Type of the license for logins created automatically. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `usergroup.external_group_name` | `string` | The name for external group. Empty if the group is not external. |
| `usergroup.organizational_unit` | `string` | The organizational unit for filtering the AD group searches. Empty if the group is not external. |
| `usergroup.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `usergroup.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `usergroup.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `usergroup.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `usergroup.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `usergroup.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `usergroup.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `usergroup.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `usergroup.import_mode` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Import mode for external groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |
| `usergroup.external_repository_name` | `string` | External repository name. unset if this group doesn't represent external repository user information. |
| `usergroup.external_repository_subject_id` | `string` | ID in the external repository. unset if this group doesn't represent external repository user information. |

---

# IRPCUserGroupsAdmin.GetUserGroupsAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/

Badges: `Administration API / specialized` `admin` `session`

Gets all normal user groups of the vault, with their members.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user-groups-admin`
- **Request:** [`GetUserGroupsAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/index.md#request)
- **Response:** [`GetUserGroupsAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupsAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`. Returns groups of type `USER_GROUP_TYPE_NORMAL`
  only; use [GetUserContainersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/index.md)
  for all types. The order is not specified.
- The built-in groups 1 and 2 have empty `members`.

<a id="request"></a>

## Request: GetUserGroupsAdminRequest

No fields.

<a id="response"></a>

## Response: GetUserGroupsAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`UserGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md) | The user groups. See [UserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md). |
| `values[].user_group` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The basic data of the group. |
| `values[].user_group.id` | `int32` | The ID of the user group. |
| `values[].user_group.name` | `string` | The name of the group. |
| `values[].user_group.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `values[].user_group.type` | [`UserGroupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md) | User group type. Values: `USER_GROUP_TYPE_NORMAL` (0), `USER_GROUP_TYPE_REPOSITORY_USER` (1), `USER_GROUP_TYPE_REPOSITORY_GROUP` (2), `USER_GROUP_TYPE_ANY` (-1). |
| `values[].is_external_windows_group` | `bool` | Is group imported from Windows domain. |
| `values[].synchronize_memberships` | `bool` | Should memberships of this group be synchronized automatically. |
| `values[].license_type_for_new_logins` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | Type of the license for logins created automatically. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `values[].external_group_name` | `string` | The name for external group. Empty if the group is not external. |
| `values[].organizational_unit` | `string` | The organizational unit for filtering the AD group searches. Empty if the group is not external. |
| `values[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `values[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `values[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `values[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `values[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `values[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `values[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `values[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `values[].import_mode` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Import mode for external groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |
| `values[].external_repository_name` | `string` | External repository name. unset if this group doesn't represent external repository user information. |
| `values[].external_repository_subject_id` | `string` | ID in the external repository. unset if this group doesn't represent external repository user information. |

<a id="related"></a>

## Related methods

- [GetUserContainersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserContainersAdmin/index.md): Gets all user groups of the vault, including the groups that represent external repository users and groups.

---

# IRPCUserGroupsAdmin.GetUserGroupSyncStatus

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus/

Badges: `Administration API / specialized` `admin` `session`

Gets the result of the last synchronization of an external Windows group.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-user-group-sync-status`
- **Request:** [`GetUserGroupSyncStatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus/index.md#request)
- **Response:** [`GetUserGroupSyncStatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `manage_users`.
- The response has no `status` when nothing has been recorded for the group, including groups
  that are not external Windows groups and unknown IDs; it does not fail.

<a id="request"></a>

## Request: GetUserGroupSyncStatusRequest

Request structure for the GetUserGroupSyncStatus method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `user_group` | `int32` | The ID of the user group. |

<a id="response"></a>

## Response: GetUserGroupSyncStatusResponse

Response structure for the GetUserGroupSyncStatus method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `status` | [`UserGroupSyncStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupSyncStatus/index.md) | The last synchronization: time, synchronized and skipped user counts, and errors. Unset if none is recorded. |
| `status.user_group_id` | `int32` | The ID of the user group. |
| `status.last_run_timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last run timestamp. |
| `status.synchronized_user_count` | `int32` | The count of synchronized users. |
| `status.skipped_user_count` | `int32` | The count of skipped users. |
| `status.last_errors` | `string` | Error string from the last run (if any). |

---

# IRPCUserGroupsAdmin.ModifyUserGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/ModifyUserGroup/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Replaces the data and members of an existing user group.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/ModifyUserGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-user-group`
- **Request:** [`ModifyUserGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/ModifyUserGroup/index.md#request)
- **Response:** [`ModifyUserGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/ModifyUserGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`.
- Send the complete group: read it with
  [GetUserGroupAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin/index.md), change what you need
  and send it back. `members` replaces the old member list. To add or remove one member, use
  [AddMemberToUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md) or
  [RemoveMemberFromUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/index.md).
- The built-in groups 1 and 2 can be renamed, but their `members` must be empty.

<a id="request"></a>

## Request: ModifyUserGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `usergroup` | [`UserGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroup/index.md) | The complete new data of the group; `user_group.id` identifies the group. |
| `usergroup.user_group` | [`UserGroupBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupBasic/index.md) | The basic data of the group. |
| `usergroup.user_group.id` | `int32` | The ID of the user group. |
| `usergroup.user_group.name` | `string` | The name of the group. |
| `usergroup.user_group.members[]` | repeated `int32` | The IDs of the members of this group (user accounts and/or user groups). |
| `usergroup.user_group.type` | [`UserGroupType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UserGroupType/index.md) | User group type. Values: `USER_GROUP_TYPE_NORMAL` (0), `USER_GROUP_TYPE_REPOSITORY_USER` (1), `USER_GROUP_TYPE_REPOSITORY_GROUP` (2), `USER_GROUP_TYPE_ANY` (-1). |
| `usergroup.is_external_windows_group` | `bool` | Is group imported from Windows domain. |
| `usergroup.synchronize_memberships` | `bool` | Should memberships of this group be synchronized automatically. |
| `usergroup.license_type_for_new_logins` | [`LicenseType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicenseType/index.md) | Type of the license for logins created automatically. Values: `LICENSE_TYPE_NONE` (0), `LICENSE_TYPE_NAMED_USER_LICENSE` (1), `LICENSE_TYPE_CONCURRENT_USER_LICENSE` (2), `LICENSE_TYPE_READ_ONLY_LICENSE` (3), `LICENSE_TYPE_VISITOR_LICENSE` (4). |
| `usergroup.external_group_name` | `string` | The name for external group. Empty if the group is not external. |
| `usergroup.organizational_unit` | `string` | The organizational unit for filtering the AD group searches. Empty if the group is not external. |
| `usergroup.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `usergroup.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `usergroup.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `usergroup.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `usergroup.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `usergroup.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `usergroup.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `usergroup.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `usergroup.import_mode` | [`ExternalGroupImportMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExternalGroupImportMode/index.md) | Import mode for external groups. Values: `EXTERNAL_GROUP_IMPORT_MODE_UNDEFINED` (0), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` (1), `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` (2). |
| `usergroup.external_repository_name` | `string` | External repository name. unset if this group doesn't represent external repository user information. |
| `usergroup.external_repository_subject_id` | `string` | ID in the external repository. unset if this group doesn't represent external repository user information. |

<a id="response"></a>

## Response: ModifyUserGroupResponse

No fields.

<a id="related"></a>

## Related methods

- [GetUserGroupAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupAdmin/index.md): Gets one user group of any type, with its members.
- [AddMemberToUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/AddMemberToUserGroup/index.md): Adds one user or group to a user group, if it is not a member yet.
- [RemoveMemberFromUserGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/index.md): Removes one user or group from a user group, if it is a member.

---

# IRPCUserGroupsAdmin.RemoveMemberFromUserGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/

Badges: `Administration API / specialized` `admin` `session`

Removes one user or group from a user group, if it is a member.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-member-from-user-group`
- **Request:** [`RemoveMemberFromUserGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/index.md#request)
- **Response:** [`RemoveMemberFromUserGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveMemberFromUserGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `manage_users` and `license_allows_modifications`.
- Removes only a direct membership.

<a id="request"></a>

## Request: RemoveMemberFromUserGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `user_group` | `int32` | The ID of the group to remove the member from. |
| `member_id` | `int32` | The user account ID, or the negated ID of a user group (-102 for group 102). |

<a id="response"></a>

## Response: RemoveMemberFromUserGroupResponse

No fields.

---

# IRPCUserGroupsAdmin.RemoveUserGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveUserGroup/

Badges: `Administration API / specialized` `admin` `session`

Removes a user group from the vault.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/RemoveUserGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-user-group`
- **Request:** [`RemoveUserGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveUserGroup/index.md#request)
- **Response:** [`RemoveUserGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/RemoveUserGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Removes the group and its memberships. Requires the vault rights `manage_users` and
  `license_allows_modifications`.
- The built-in groups 1 and 2 cannot be removed.

<a id="request"></a>

## Request: RemoveUserGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the user group to remove. |

<a id="response"></a>

## Response: RemoveUserGroupResponse

No fields.

---

# IRPCUserGroupsAdmin.SyncExternalWindowsGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/SyncExternalWindowsGroup/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Updates the members of an external Windows group from the domain directory.

- **Service:** [User groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/index.md) `MFiles.IRPCUserGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCUserGroupsAdmin/SyncExternalWindowsGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/sync-external-windows-group`
- **Request:** [`SyncExternalWindowsGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/SyncExternalWindowsGroup/index.md#request)
- **Response:** [`SyncExternalWindowsGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/SyncExternalWindowsGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Reads the group's members from the directory and updates the group, adding user accounts for
  new members as needed. Large groups can take a long time.
- Requires the vault right `manage_users`. A group that is not an external Windows group fails;
  an unknown ID fails with "Not found.".
- The result is recorded for
  [GetUserGroupSyncStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus/index.md).

<a id="request"></a>

## Request: SyncExternalWindowsGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the external Windows group to synchronize. |

<a id="response"></a>

## Response: SyncExternalWindowsGroupResponse

No fields.

<a id="related"></a>

## Related methods

- [GetUserGroupSyncStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCUserGroupsAdmin/GetUserGroupSyncStatus/index.md): Gets the result of the last synchronization of an external Windows group.

---

# Object type administration (IRPCObjectTypesAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/

Administers object types and value lists: reads their full definitions, adds, modifies, converts
and removes them, and manages value list items with administrator rights.

Use this interface to add, remove and modify object types and their
contents. This interface is intended to be used with administrative
value list operations as well. Value lists are just seen as simple object
types.

- **gRPC service:** `MFiles.IRPCObjectTypesAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 18
- **Proto file:** [`mfiles/IRPCObjectTypesAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCObjectTypesAdmin.proto)

<a id="overview"></a>

## Overview

This is the administrator's side of [IRPCObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md) and
[IRPCValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md). M-Files Admin and administrative tools call it;
ordinary applications read the structure with the Vault API instead.

| | Vault API (read side) | This service |
| --- | --- | --- |
| Data | [ValueList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md): names, flags, the caller's permissions | [ValueListAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md): the same plus external database connection, column mappings, automatic permissions, aliases |
| Rights | none | `read_all_metadata_structure` to read, `change_metadata_structure` to write |
| Calls | [GetObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md), [GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md) | [GetObjectTypeDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDefs/index.md), [GetValueListDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md) |

- **Session and rights.** Every method requires a vault session. Reads need the vault right
  `read_all_metadata_structure`; writes need `change_metadata_structure` and
  `license_allows_modifications`. The vault role full control grants them. A normal user gets
  "Access denied." (gRPC status `UNKNOWN`, error codes 0x800407E4 and 0x800400A9).
  Connecting an object type to an external database also needs the server right `run_code`
  (see [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md)).
- **Read the definitions**:
  [GetObjectTypeDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDefs/index.md),
  [GetValueListDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md),
  [GetObjectTypeDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/index.md).
- **Change the definitions**:
  [AddObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectType/index.md),
  [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md),
  [ConvertValueListToObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ConvertValueListToObjectType/index.md),
  [RemoveObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectType/index.md). Read the current
  definition first, change it, and send the whole [ValueListAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md)
  back.
- **External object types** (items read from an external database or connector):
  [ParseSQLSelectStatement](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement/index.md),
  [RefreshExternalObjectTypeColumnMappings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RefreshExternalObjectTypeColumnMappings/index.md),
  [GetExternalObjectTypePlugins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePlugins/index.md),
  [GetExternalObjectTypePluginConnectionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePluginConnectionInfo/index.md).
- **Value list items** (not objects of real object types):
  [AddObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/index.md),
  [UpdateObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/UpdateObjectTypeItem/index.md),
  [RemoveObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md),
  [ChangeObjectTypeItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemPermissions/index.md),
  [ChangeObjectTypeItemIcon](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemIcon/index.md),
  [ChangeObjectTypeItemAutomaticPermissionsForObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemAutomaticPermissionsForObjects/index.md).
  Users without administrator rights use the `...FromClient` methods of
  [IRPCValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/index.md) instead. Classes (list 1) and class groups
  (list 2) are not items here: use [IRPCPropertyDefsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)
  and [IRPCDocClassGroupsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md).

**Metadata structure version.** Adding, modifying, converting and removing an object type or value list
increments the vault's metadata structure version by one when the change commits, so clients that cache
the structure reload it (see
[Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md)). These methods do
not send the `mfiles-metadata-version-bin` trailer themselves; read the new value
with [GetMetadataStructureVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/index.md) or from
the trailer of the next call. Changing value list items does not change the metadata structure version,
except permission changes on items of structure lists such as classes. Changes that update the
metadata structure version fail while the vault is being archived or restored.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectType/index.md) | Creates a new object type or value list. | `admin` `session` |
| [AddObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/index.md) | Adds an item to a value list as an administrator. | `admin` `session` |
| [AreAutomaticPermissionsUsed](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AreAutomaticPermissionsUsed/index.md) | Tells whether any item uses automatic permissions, in one object type or value list or in all of them. | `admin` `session` `idempotent` |
| [ChangeObjectTypeItemAutomaticPermissionsForObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemAutomaticPermissionsForObjects/index.md) | Sets or clears the automatic permissions that an item (a value list item or an object) gives to the objects that refer to it. | `admin` `session` `idempotent` |
| [ChangeObjectTypeItemIcon](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemIcon/index.md) | Sets or clears the icon of a value list item. | `admin` `session` `idempotent` |
| [ChangeObjectTypeItemPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemPermissions/index.md) | Replaces the permissions (ACL) of a value list item. | `admin` `session` `idempotent` |
| [ConvertValueListToObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ConvertValueListToObjectType/index.md) | Converts a value list, and the lists that own it or that it owns, into real object types. | `admin` `session` |
| [GetExternalObjectTypePluginConnectionInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePluginConnectionInfo/index.md) | Gets the configuration domain and status message of a connector for one object type. | `admin` `session` |
| [GetExternalObjectTypePlugins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePlugins/index.md) | Lists the installed connectors (vault applications) that can provide the items of external object types. | `admin` `session` |
| [GetObjectTypeDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/index.md) | Gets the full administrative definition of one object type or value list. | `admin` `session` |
| [GetObjectTypeDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDefs/index.md) | Gets the full administrative definitions of all real object types. | `admin` `session` `idempotent` |
| [GetValueListDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md) | Gets the full administrative definitions of all object types and value lists. | `admin` `session` `idempotent` |
| [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md) | Saves a changed definition of an object type or value list. | `admin` `session` `idempotent` |
| [ParseSQLSelectStatement](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement/index.md) | Connects to an external database and returns the source table and columns of a SELECT statement, to set up the column mappings of an external object type. | `admin` `session` `idempotent` |
| [RefreshExternalObjectTypeColumnMappings](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RefreshExternalObjectTypeColumnMappings/index.md) | Re-reads the columns of an external object type's SELECT statement, merges them with the existing column mappings, and saves the object type. | `admin` `session` |
| [RemoveObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectType/index.md) | Removes an object type or value list together with its items, classes and dependent views. | `admin` `session` |
| [RemoveObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md) | Deletes an item of a value list as an administrator. | `admin` `session` |
| [UpdateObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/UpdateObjectTypeItem/index.md) | Updates an item of a value list (for example its name, parent or owner) as an administrator. | `admin` `session` `idempotent` |

---

# IRPCObjectTypesAdmin.AddObjectType

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectType/

Badges: `Administration API / specialized` `admin` `session`

Creates a new object type or value list.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/AddObjectType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-object-type`
- **Request:** [`AddObjectTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectType/index.md#request)
- **Response:** [`AddObjectTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectType/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`. An external
  connection string also requires the server right `run_code` (see
  [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md)).
- Creates database tables and the owner property definition of the new list.
- Increments the metadata structure version.

<a id="request"></a>

## Request: AddObjectTypeRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_type` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The new object type or value list. `object_type.is_real_object_type` chooses between the two. The ID, GUID and owner property definition are ignored and assigned by the server. |
| `obj_type.object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `obj_type.object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `obj_type.object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `obj_type.object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `obj_type.object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `obj_type.object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `obj_type.object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `obj_type.object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `obj_type.object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `obj_type.object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `obj_type.object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `obj_type.object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `obj_type.object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `obj_type.object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `obj_type.object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `obj_type.object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `obj_type.object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `obj_type.object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `obj_type.object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `obj_type.object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `obj_type.object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `obj_type.object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `obj_type.object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `obj_type.object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `obj_type.object_type.view_id` | `int32` | The ID of the object type specific view. |
| `obj_type.database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `obj_type.database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `obj_type.database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `obj_type.database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `obj_type.database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `obj_type.database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `obj_type.database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `obj_type.database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `obj_type.database_column_mappings[].object_type` | `int32` | Object type ID. |
| `obj_type.database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `obj_type.database_column_mappings[].source_field` | `string` | Source field name. |
| `obj_type.database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `obj_type.database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `obj_type.database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `obj_type.database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `obj_type.automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `obj_type.automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `obj_type.automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `obj_type.automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `obj_type.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `obj_type.tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `obj_type.tags[].name` | `string` | The name of the namespace. |
| `obj_type.tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `obj_type.version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |

<a id="response"></a>

## Response: AddObjectTypeResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_type_result` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The new definition with its ID, GUID and owner property definition (`object_type.owner_property_def`) set. |
| `obj_type_result.object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `obj_type_result.object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `obj_type_result.object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `obj_type_result.object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `obj_type_result.object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `obj_type_result.object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `obj_type_result.object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `obj_type_result.object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `obj_type_result.object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `obj_type_result.object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `obj_type_result.object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `obj_type_result.object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `obj_type_result.object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `obj_type_result.object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `obj_type_result.object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `obj_type_result.object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `obj_type_result.object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `obj_type_result.object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `obj_type_result.object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `obj_type_result.object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `obj_type_result.object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `obj_type_result.object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `obj_type_result.object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `obj_type_result.object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `obj_type_result.object_type.view_id` | `int32` | The ID of the object type specific view. |
| `obj_type_result.database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `obj_type_result.database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `obj_type_result.database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `obj_type_result.database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `obj_type_result.database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `obj_type_result.database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `obj_type_result.database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `obj_type_result.database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `obj_type_result.database_column_mappings[].object_type` | `int32` | Object type ID. |
| `obj_type_result.database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `obj_type_result.database_column_mappings[].source_field` | `string` | Source field name. |
| `obj_type_result.database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `obj_type_result.database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `obj_type_result.database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `obj_type_result.database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `obj_type_result.automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `obj_type_result.automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `obj_type_result.automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `obj_type_result.automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `obj_type_result.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `obj_type_result.tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `obj_type_result.tags[].name` | `string` | The name of the namespace. |
| `obj_type_result.tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `obj_type_result.version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |

<a id="related"></a>

## Related methods

- [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md): Saves a changed definition of an object type or value list.
- [AddObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/index.md): Adds an item to a value list as an administrator.

---

# IRPCObjectTypesAdmin.AddObjectTypeItem

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/

Badges: `Administration API / specialized` `admin` `session`

Adds an item to a value list as an administrator.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-object-type-item`
- **Request:** [`AddObjectTypeItemRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/index.md#request)
- **Response:** [`AddObjectTypeItemResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`; the list's own
  permissions are not checked. Users without these rights use
  [AddValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md).
- Only for plain value lists. A real object type fails with "Not found." (create objects with
  [IRPCObjectOperations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/index.md)); classes (1), class groups (2) and
  list 18 are refused with an invalid-argument error, and external lists are refused.
- `has_parent` is allowed only in hierarchical lists, `has_owner` only in lists that are not
  hierarchical.
- In Traditional folders (list 4) the call returns an existing matching folder instead of adding
  a duplicate.

<a id="request"></a>

## Request: AddObjectTypeItemRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vlitem` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The item to add. `item_info.obj_id.type` names the value list; the item ID and GUID are ignored and assigned by the server. |
| `vlitem.item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item. |
| `vlitem.item_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object id or value list item id. Includes the object type or value list id. |
| `vlitem.item_info.name` | `string` | The name of the item. |
| `vlitem.item_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this item's external ID. Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5). |
| `vlitem.item_info.external_id` | `string` | The external ID (display ID) of this item. unset means that the external ID is the same as the internal ID. |
| `vlitem.item_info.guid` | `string` | GUID for the item. |
| `vlitem.item_info.options` | [`ITEMFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ITEMFLAGS/index.md) | Bit flags that provide additional information on the item (e.g. is the object deleted). |
| `vlitem.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `vlitem.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `vlitem.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `vlitem.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `vlitem.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `vlitem.owner_name` | `string` | The name of the owner item. |
| `vlitem.automatic_permissions` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | If set, specifies the automatic permissions for an object for which the user selects this item. |
| `vlitem.automatic_permissions.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `vlitem.automatic_permissions.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `vlitem.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `vlitem.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains the icon of this item in .ICO format. |
| `vlitem.icon.value` | `bytes` | Array of bytes. |

<a id="response"></a>

## Response: AddObjectTypeItemResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `result` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The item as stored, with its new ID, GUID and default automatic permissions. |
| `result.item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item. |
| `result.item_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object id or value list item id. Includes the object type or value list id. |
| `result.item_info.name` | `string` | The name of the item. |
| `result.item_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this item's external ID. Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5). |
| `result.item_info.external_id` | `string` | The external ID (display ID) of this item. unset means that the external ID is the same as the internal ID. |
| `result.item_info.guid` | `string` | GUID for the item. |
| `result.item_info.options` | [`ITEMFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ITEMFLAGS/index.md) | Bit flags that provide additional information on the item (e.g. is the object deleted). |
| `result.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `result.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `result.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `result.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `result.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `result.owner_name` | `string` | The name of the owner item. |
| `result.automatic_permissions` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | If set, specifies the automatic permissions for an object for which the user selects this item. |
| `result.automatic_permissions.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `result.automatic_permissions.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `result.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `result.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains the icon of this item in .ICO format. |
| `result.icon.value` | `bytes` | Array of bytes. |

<a id="related"></a>

## Related methods

- [IRPCValueLists.AddValueListItemFromClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/AddValueListItemFromClient/index.md): Adds a new item to a value list, as a user.
- [AddObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectType/index.md): Creates a new object type or value list.

---

# IRPCObjectTypesAdmin.AreAutomaticPermissionsUsed

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AreAutomaticPermissionsUsed/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Tells whether any item uses automatic permissions, in one object type or value list or in all
of them.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/AreAutomaticPermissionsUsed`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/are-automatic-permissions-used`
- **Request:** [`AreAutomaticPermissionsUsedRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AreAutomaticPermissionsUsed/index.md#request)
- **Response:** [`AreAutomaticPermissionsUsedResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AreAutomaticPermissionsUsed/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session; no vault rights are needed (a normal user's call succeeded). Read-only.

<a id="request"></a>

## Request: AreAutomaticPermissionsUsedRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `all_object_types` | `bool` | True to check every object type and value list; `object_type` is then ignored. |
| `object_type` | `int32` | The object type or value list to check when `all_object_types` is false. |

<a id="response"></a>

## Response: AreAutomaticPermissionsUsedResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `automatic_permissions_used` | `bool` | Receives true if automatic permissions are in use. |

---

# IRPCObjectTypesAdmin.ChangeObjectTypeItemAutomaticPermissionsForObjects

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemAutomaticPermissionsForObjects/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Sets or clears the automatic permissions that an item (a value list item or an object) gives to
the objects that refer to it.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemAutomaticPermissionsForObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/change-object-type-item-automatic-permissions-for-objects`
- **Request:** [`ChangeObjectTypeItemAutomaticPermissionsForObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemAutomaticPermissionsForObjects/index.md#request)
- **Response:** [`ChangeObjectTypeItemAutomaticPermissionsForObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemAutomaticPermissionsForObjects/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`, and read access to
  the item.
- Applying the change to existing objects runs as background tasks, returned in
  `async_task_ids`; follow them with
  [GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md).
- For classes (list 1) the change increments the metadata structure version.

<a id="request"></a>

## Request: ChangeObjectTypeItemAutomaticPermissionsForObjectsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The value list item or object: `type` is the value list or object type ID, `item_id.internal_id` the item or object ID. |
| `obj_id.type` | `int32` | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
| `obj_id.item_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the object within its type, in `item_id.internal_id`. |
| `obj_id.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_id.item_id.external_repository_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | Used only for objects in external repositories (external connectors). Leave it unset for objects stored in the vault. |
| `utf8szaacl` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The new automatic permissions. Ignored when `acl_valid` is false. |
| `utf8szaacl.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `utf8szaacl.permissions.id` | `int32` | Named ACL ID. |
| `utf8szaacl.permissions.name` | `string` | The name of the named ACL. |
| `utf8szaacl.permissions.type` | [`NACLType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) | The type of the NACL. Values: `NACLTYPE_NONE` (0), `NACLTYPE_NORMAL` (1), `NACLTYPE_INTERNAL` (2). |
| `utf8szaacl.permissions.acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The predefined permissions. This defines the ACL which this named ACL encapsulates. |
| `utf8szaacl.permissions.guid` | `string` | GUID for the NACL. |
| `utf8szaacl.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `utf8szaacl.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `acl_valid` | `bool` | False to remove the item's automatic permissions. |
| `automatic_permissions_forced_active` | `bool` | True to make the new automatic permissions active on the referring objects, false to add them inactive. No effect when `acl_valid` is false. |

<a id="response"></a>

## Response: ChangeObjectTypeItemAutomaticPermissionsForObjectsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `async_task_ids[]` | repeated [`AsyncTaskID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTaskID/index.md) | Asynchronous task identifiers, if any, related to the change. |
| `async_task_ids[].id` | `int64` | Task ID. |
| `async_task_ids[].type` | `string` | Task type name. |
| `async_task_ids[].definition` | `string` | The display string of the task definition. |

<a id="related"></a>

## Related methods

- [IRPCBackgroundOperationsAdmin.GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md): Gets one asynchronous task by ID.

---

# IRPCObjectTypesAdmin.ChangeObjectTypeItemIcon

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemIcon/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Sets or clears the icon of a value list item.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemIcon`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/change-object-type-item-icon`
- **Request:** [`ChangeObjectTypeItemIconRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemIcon/index.md#request)
- **Response:** [`ChangeObjectTypeItemIconResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemIcon/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- Fails with "Access denied." for lists whose items cannot have icons.
- Does not change the metadata structure version: clients see the new icon when they reload the list's
  items.

<a id="request"></a>

## Request: ChangeObjectTypeItemIconRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The item: `type` is the value list ID, `item_id.internal_id` the item ID. |
| `obj_id.type` | `int32` | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
| `obj_id.item_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the object within its type, in `item_id.internal_id`. |
| `obj_id.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_id.item_id.external_repository_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | Used only for objects in external repositories (external connectors). Leave it unset for objects stored in the vault. |
| `icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | The new icon, or unset to remove it. |
| `icon.value` | `bytes` | Array of bytes. |

<a id="response"></a>

## Response: ChangeObjectTypeItemIconResponse

No fields.

---

# IRPCObjectTypesAdmin.ChangeObjectTypeItemPermissions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemPermissions/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Replaces the permissions (ACL) of a value list item.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemPermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/change-object-type-item-permissions`
- **Request:** [`ChangeObjectTypeItemPermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemPermissions/index.md#request)
- **Response:** [`ChangeObjectTypeItemPermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ChangeObjectTypeItemPermissions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- Only for items of plain value lists; change object permissions with the object operations.
- For items of the structure lists (classes, class groups, workflows, states, state
  transitions, external locations) the change increments the metadata structure version.

<a id="request"></a>

## Request: ChangeObjectTypeItemPermissionsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The item: `type` is the value list ID, `item_id.internal_id` the item ID. |
| `obj_id.type` | `int32` | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
| `obj_id.item_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the object within its type, in `item_id.internal_id`. |
| `obj_id.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_id.item_id.external_repository_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | Used only for objects in external repositories (external connectors). Leave it unset for objects stored in the vault. |
| `utf8szacl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The new [AccessControlList](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) of the item. |
| `utf8szacl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `utf8szacl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `utf8szacl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `utf8szacl.custom_component.named_acl_id` | `int32` | Specifies the named ACL link of this component. |
| `utf8szacl.custom_component.has_named_acl` | `bool` | True if the component links to a named ACL (`named_acl_id`). |
| `utf8szacl.custom_component.current_user_id` | `int32` | Specifies the current user binding of this component. |
| `utf8szacl.custom_component.has_current_user` | `bool` | True if the component has an access control entry for the current user. |
| `utf8szacl.custom_component.permissions[]` | repeated [`AccessControlEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlEntry/index.md) | The access control entry datas. The data belongs to the key in the corresponding index. |
| `utf8szacl.custom_component.overridability_permissions[]` | repeated [`AccessControlEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlEntry/index.md) | Overridability permission data of this ACL component. |
| `utf8szacl.custom_component.status` | [`ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACCESSCONTROLLISTCOMPONENTSTATUSFLAGS/index.md) | Modification status of this component. |
| `utf8szacl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `utf8szacl.restrictive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `utf8szacl.restrictive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |
| `utf8szacl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `utf8szacl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `utf8szacl.additive_components[].key` | [`AccessControlListComponentKey`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentKey/index.md) | Access control list component. |
| `utf8szacl.additive_components[].component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Access control list component. |

<a id="response"></a>

## Response: ChangeObjectTypeItemPermissionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `visible` | `bool` | True if the caller can still see the item under the new ACL. |

---

# IRPCObjectTypesAdmin.ConvertValueListToObjectType

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ConvertValueListToObjectType/

Badges: `Administration API / specialized` `admin` `session`

Converts a value list, and the lists that own it or that it owns, into real object types.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/ConvertValueListToObjectType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/convert-value-list-to-object-type`
- **Request:** [`ConvertValueListToObjectTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ConvertValueListToObjectType/index.md#request)
- **Response:** [`ConvertValueListToObjectTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ConvertValueListToObjectType/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Changes the vault's database structure; there is no method that converts back.
- Requires `change_metadata_structure` and `license_allows_modifications`.
- Stops background refreshing of the list while converting.
- Increments the metadata structure version.

<a id="request"></a>

## Request: ConvertValueListToObjectTypeRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `value_list` | `int32` | The ID of the value list to convert. |

<a id="response"></a>

## Response: ConvertValueListToObjectTypeResponse

No fields.

---

# IRPCObjectTypesAdmin.GetExternalObjectTypePluginConnectionInfo

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePluginConnectionInfo/

Badges: `Administration API / specialized` `admin` `session`

Gets the configuration domain and status message of a connector for one object type.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePluginConnectionInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-external-object-type-plugin-connection-info`
- **Request:** [`GetExternalObjectTypePluginConnectionInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePluginConnectionInfo/index.md#request)
- **Response:** [`GetExternalObjectTypePluginConnectionInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePluginConnectionInfo/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`. The answer comes from the connector; M-Files Admin uses
  it to open the connector's configuration.

<a id="request"></a>

## Request: GetExternalObjectTypePluginConnectionInfoRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `plugin_guid` | `string` | The GUID of the connector, from [GetExternalObjectTypePlugins](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePlugins/index.md). |
| `object_type` | `int32` | The ID of the object type. |

<a id="response"></a>

## Response: GetExternalObjectTypePluginConnectionInfoResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `domain_id` | `string` | Domain ID for the object type connection. |
| `message` | `string` | Info message about the configuration/status. |

---

# IRPCObjectTypesAdmin.GetExternalObjectTypePlugins

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePlugins/

Badges: `Administration API / specialized` `admin` `session`

Lists the installed connectors (vault applications) that can provide the items of external
object types.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePlugins`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-external-object-type-plugins`
- **Request:** [`GetExternalObjectTypePluginsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePlugins/index.md#request)
- **Response:** [`GetExternalObjectTypePluginsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetExternalObjectTypePlugins/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
- Empty when no connector is installed (as in the Sample Vault).

<a id="request"></a>

## Request: GetExternalObjectTypePluginsRequest

No fields.

<a id="response"></a>

## Response: GetExternalObjectTypePluginsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `plugin_infos[]` | repeated [`ExternalObjectTypePluginInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalObjectTypePluginInfo/index.md) | One [ExternalObjectTypePluginInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalObjectTypePluginInfo/index.md) per installed connector. |
| `plugin_infos[].guid` | `string` | The service identifier. |
| `plugin_infos[].name` | `string` | The application name. |
| `plugin_infos[].version` | `string` | The application version (author set). |
| `plugin_infos[].description` | `string` | The application description. |
| `plugin_infos[].publisher` | `string` | The application publisher. |
| `plugin_infos[].configuration_domain_id` | `string` | The configuration domain of the service. |
| `plugin_infos[].initial_page_to_open` | `string` | The initial page to open in configuration dialog. |
| `plugin_infos[].object_types[]` | repeated `int32` | The object type IDs that have a configuration. |

---

# IRPCObjectTypesAdmin.GetObjectTypeDef

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/

Badges: `Administration API / specialized` `admin` `session`

Gets the full administrative definition of one object type or value list.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-type-def`
- **Request:** [`GetObjectTypeDefRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/index.md#request)
- **Response:** [`GetObjectTypeDefResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
- An unknown ID fails with "Not found.". Same data as one element of
  [GetValueListDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md).

<a id="request"></a>

## Request: GetObjectTypeDefRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `object_type` | `int32` | The ID of the object type or value list. |

<a id="response"></a>

## Response: GetObjectTypeDefResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_type_result` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The definition. See [ValueListAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md). |
| `obj_type_result.object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `obj_type_result.object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `obj_type_result.object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `obj_type_result.object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `obj_type_result.object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `obj_type_result.object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `obj_type_result.object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `obj_type_result.object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `obj_type_result.object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `obj_type_result.object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `obj_type_result.object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `obj_type_result.object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `obj_type_result.object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `obj_type_result.object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `obj_type_result.object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `obj_type_result.object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `obj_type_result.object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `obj_type_result.object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `obj_type_result.object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `obj_type_result.object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `obj_type_result.object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `obj_type_result.object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `obj_type_result.object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `obj_type_result.object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `obj_type_result.object_type.view_id` | `int32` | The ID of the object type specific view. |
| `obj_type_result.database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `obj_type_result.database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `obj_type_result.database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `obj_type_result.database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `obj_type_result.database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `obj_type_result.database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `obj_type_result.database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `obj_type_result.database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `obj_type_result.database_column_mappings[].object_type` | `int32` | Object type ID. |
| `obj_type_result.database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `obj_type_result.database_column_mappings[].source_field` | `string` | Source field name. |
| `obj_type_result.database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `obj_type_result.database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `obj_type_result.database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `obj_type_result.database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `obj_type_result.automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `obj_type_result.automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `obj_type_result.automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `obj_type_result.automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `obj_type_result.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `obj_type_result.tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `obj_type_result.tags[].name` | `string` | The name of the namespace. |
| `obj_type_result.tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `obj_type_result.version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |

<a id="related"></a>

## Related methods

- [GetValueListDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md): Gets the full administrative definitions of all object types and value lists.

---

# IRPCObjectTypesAdmin.GetObjectTypeDefs

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDefs/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the full administrative definitions of all real object types.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDefs`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-type-defs`
- **Request:** [`GetObjectTypeDefsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDefs/index.md#request)
- **Response:** [`GetObjectTypeDefsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDefs/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.". Users
  without the right call [GetObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md).
- Returns real object types only (11 in the Sample Vault). For object types and value lists
  together use [GetValueListDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md).
- Names are in the session language.

<a id="request"></a>

## Request: GetObjectTypeDefsRequest

No fields.

<a id="response"></a>

## Response: GetObjectTypeDefsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `object_types[]` | repeated [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | One [ValueListAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) per object type. |
| `object_types[].object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `object_types[].object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `object_types[].object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `object_types[].object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `object_types[].object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `object_types[].object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `object_types[].object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `object_types[].object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `object_types[].object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `object_types[].object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `object_types[].object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `object_types[].object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `object_types[].object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `object_types[].object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `object_types[].object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `object_types[].object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `object_types[].object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `object_types[].object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `object_types[].object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `object_types[].object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `object_types[].object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `object_types[].object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `object_types[].object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `object_types[].object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `object_types[].object_type.view_id` | `int32` | The ID of the object type specific view. |
| `object_types[].database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `object_types[].database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `object_types[].database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `object_types[].database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `object_types[].database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `object_types[].database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `object_types[].database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `object_types[].database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `object_types[].database_column_mappings[].object_type` | `int32` | Object type ID. |
| `object_types[].database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `object_types[].database_column_mappings[].source_field` | `string` | Source field name. |
| `object_types[].database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `object_types[].database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `object_types[].database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `object_types[].database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `object_types[].automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `object_types[].automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `object_types[].automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `object_types[].automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `object_types[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `object_types[].tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `object_types[].tags[].name` | `string` | The name of the namespace. |
| `object_types[].tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `object_types[].version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |

<a id="related"></a>

## Related methods

- [IRPCObjectTypes.GetObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/GetObjectTypes/index.md): Gets all object types (real object types only, not plain value lists), with their icons.
- [GetValueListDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md): Gets the full administrative definitions of all object types and value lists.

---

# IRPCObjectTypesAdmin.GetValueListDefs

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the full administrative definitions of all object types and value lists.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/GetValueListDefs`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-value-list-defs`
- **Request:** [`GetValueListDefsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md#request)
- **Response:** [`GetValueListDefsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetValueListDefs/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.". Users
  without the right call [GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md).
- Returns both plain value lists and real object types (29 in the Sample Vault, including the 11
  object types); `object_type.is_real_object_type` tells them apart.

<a id="request"></a>

## Request: GetValueListDefsRequest

No fields.

<a id="response"></a>

## Response: GetValueListDefsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `object_types[]` | repeated [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | One [ValueListAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) per object type or value list. |
| `object_types[].object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `object_types[].object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `object_types[].object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `object_types[].object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `object_types[].object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `object_types[].object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `object_types[].object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `object_types[].object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `object_types[].object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `object_types[].object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `object_types[].object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `object_types[].object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `object_types[].object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `object_types[].object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `object_types[].object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `object_types[].object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `object_types[].object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `object_types[].object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `object_types[].object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `object_types[].object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `object_types[].object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `object_types[].object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `object_types[].object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `object_types[].object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `object_types[].object_type.view_id` | `int32` | The ID of the object type specific view. |
| `object_types[].database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `object_types[].database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `object_types[].database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `object_types[].database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `object_types[].database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `object_types[].database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `object_types[].database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `object_types[].database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `object_types[].database_column_mappings[].object_type` | `int32` | Object type ID. |
| `object_types[].database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `object_types[].database_column_mappings[].source_field` | `string` | Source field name. |
| `object_types[].database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `object_types[].database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `object_types[].database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `object_types[].database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `object_types[].automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `object_types[].automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `object_types[].automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `object_types[].automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `object_types[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `object_types[].tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `object_types[].tags[].name` | `string` | The name of the namespace. |
| `object_types[].tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `object_types[].version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |

<a id="related"></a>

## Related methods

- [IRPCValueLists.GetValueLists](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCValueLists/GetValueLists/index.md): Gets all value lists of the vault, including the object types, without icons.

---

# IRPCObjectTypesAdmin.ModifyObjectType

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Saves a changed definition of an object type or value list.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/ModifyObjectType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-object-type`
- **Request:** [`ModifyObjectTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md#request)
- **Response:** [`ModifyObjectTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- Setting or changing the external database connection string, or re-enabling a disabled
  external connection, also requires the server right `run_code` (system administrator), unless
  the connection string matches the providers and settings that the server allows for vault
  administrators. The server connects to that data source itself.
- Turning separate property storage on or off for a real object type **takes the vault offline**
  while the property data is moved.
- Changes to automatic permissions are applied to existing objects by background tasks, returned
  in `async_task_ids`; follow them with
  [GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md).
- Increments the metadata structure version.

<a id="request"></a>

## Request: ModifyObjectTypeRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_type` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The complete new definition; `object_type.id` identifies the object type. Start from [GetObjectTypeDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/index.md). |
| `obj_type.object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `obj_type.object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `obj_type.object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `obj_type.object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `obj_type.object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `obj_type.object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `obj_type.object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `obj_type.object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `obj_type.object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `obj_type.object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `obj_type.object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `obj_type.object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `obj_type.object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `obj_type.object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `obj_type.object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `obj_type.object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `obj_type.object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `obj_type.object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `obj_type.object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `obj_type.object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `obj_type.object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `obj_type.object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `obj_type.object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `obj_type.object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `obj_type.object_type.view_id` | `int32` | The ID of the object type specific view. |
| `obj_type.database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `obj_type.database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `obj_type.database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `obj_type.database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `obj_type.database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `obj_type.database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `obj_type.database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `obj_type.database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `obj_type.database_column_mappings[].object_type` | `int32` | Object type ID. |
| `obj_type.database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `obj_type.database_column_mappings[].source_field` | `string` | Source field name. |
| `obj_type.database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `obj_type.database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `obj_type.database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `obj_type.database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `obj_type.automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `obj_type.automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `obj_type.automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `obj_type.automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `obj_type.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `obj_type.tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `obj_type.tags[].name` | `string` | The name of the namespace. |
| `obj_type.tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `obj_type.version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |
| `automatic_permissions_forced_active` | `bool` | True to make changed automatic permissions active on the referring objects, false to add them inactive. |
| `entity_version_checks_enabled` | `bool` | If true, the entity (ObjectType) version is tracked by versions conflict detection feature. |

<a id="response"></a>

## Response: ModifyObjectTypeResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `result` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The definition as stored. |
| `result.object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `result.object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `result.object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `result.object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `result.object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `result.object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `result.object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `result.object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `result.object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `result.object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `result.object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `result.object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `result.object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `result.object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `result.object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `result.object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `result.object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `result.object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `result.object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `result.object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `result.object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `result.object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `result.object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `result.object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `result.object_type.view_id` | `int32` | The ID of the object type specific view. |
| `result.database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `result.database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `result.database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `result.database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `result.database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `result.database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `result.database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `result.database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `result.database_column_mappings[].object_type` | `int32` | Object type ID. |
| `result.database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `result.database_column_mappings[].source_field` | `string` | Source field name. |
| `result.database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `result.database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `result.database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `result.database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `result.automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `result.automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `result.automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `result.automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `result.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `result.tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `result.tags[].name` | `string` | The name of the namespace. |
| `result.tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `result.version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |
| `async_task_ids[]` | repeated [`AsyncTaskID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTaskID/index.md) | Asynchronous task identifiers, if any, related to the change. |
| `async_task_ids[].id` | `int64` | Task ID. |
| `async_task_ids[].type` | `string` | Task type name. |
| `async_task_ids[].definition` | `string` | The display string of the task definition. |

<a id="related"></a>

## Related methods

- [IRPCBackgroundOperationsAdmin.GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md): Gets one asynchronous task by ID.

---

# IRPCObjectTypesAdmin.ParseSQLSelectStatement

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Connects to an external database and returns the source table and columns of a SELECT
statement, to set up the column mappings of an external object type.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/parse-sqlselect-statement`
- **Request:** [`ParseSQLSelectStatementRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement/index.md#request)
- **Response:** [`ParseSQLSelectStatementResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`. The server opens the
  connection itself, so the call also requires the server right `run_code` (system
  administrator), unless the connection string matches the providers and settings that the
  server allows for vault administrators.
- An empty `connection_string` (the vault's own database) is always refused with
  "Access denied.".
- Read-only: nothing is saved. Apply the result with
  [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md).

<a id="request"></a>

## Request: ParseSQLSelectStatementRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `connection_string` | `string` | OLE DB connection string of the external database. |
| `select_statement` | `string` | The SELECT statement to parse. |

<a id="response"></a>

## Response: ParseSQLSelectStatementResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `source_table` | `string` | The name of the source table. |
| `putf8szcolmappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | One mapping per column in the SELECT list, with only the source column details set; fill in the target property definitions yourself. |
| `putf8szcolmappings[].object_type` | `int32` | Object type ID. |
| `putf8szcolmappings[].ordinal` | `int32` | One-based source field ordinal. |
| `putf8szcolmappings[].source_field` | `string` | Source field name. |
| `putf8szcolmappings[].data_type` | `uint32` | Source field's data type. |
| `putf8szcolmappings[].target_property_def` | `int32` | Target property definition. |
| `putf8szcolmappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `putf8szcolmappings[].can_update` | `bool` | Is the source field part of update operations? |

<a id="related"></a>

## Related methods

- [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md): Saves a changed definition of an object type or value list.

---

# IRPCObjectTypesAdmin.RefreshExternalObjectTypeColumnMappings

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RefreshExternalObjectTypeColumnMappings/

Badges: `Administration API / specialized` `admin` `session`

Re-reads the columns of an external object type's SELECT statement, merges them with the
existing column mappings, and saves the object type.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/RefreshExternalObjectTypeColumnMappings`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/refresh-external-object-type-column-mappings`
- **Request:** [`RefreshExternalObjectTypeColumnMappingsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RefreshExternalObjectTypeColumnMappings/index.md#request)
- **Response:** [`RefreshExternalObjectTypeColumnMappingsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RefreshExternalObjectTypeColumnMappings/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Saves the `obj_type` you send, with refreshed `database_column_mappings`. Send the current
  definition from [GetObjectTypeDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/index.md):
  any other change in it is saved too.
- Columns that already had a mapping keep their target property definition and insert and update
  settings; new columns come back unmapped.
- Same rights as
  [ParseSQLSelectStatement](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement/index.md), which it
  calls with the object type's connection string and SELECT statement.
- Unlike [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md), it does not
  increment the metadata structure version.

<a id="request"></a>

## Request: RefreshExternalObjectTypeColumnMappingsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_type` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The object type's current definition; its connection string and SELECT statement are used to read the columns. |
| `obj_type.object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `obj_type.object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `obj_type.object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `obj_type.object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `obj_type.object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `obj_type.object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `obj_type.object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `obj_type.object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `obj_type.object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `obj_type.object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `obj_type.object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `obj_type.object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `obj_type.object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `obj_type.object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `obj_type.object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `obj_type.object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `obj_type.object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `obj_type.object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `obj_type.object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `obj_type.object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `obj_type.object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `obj_type.object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `obj_type.object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `obj_type.object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `obj_type.object_type.view_id` | `int32` | The ID of the object type specific view. |
| `obj_type.database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `obj_type.database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `obj_type.database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `obj_type.database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `obj_type.database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `obj_type.database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `obj_type.database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `obj_type.database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `obj_type.database_column_mappings[].object_type` | `int32` | Object type ID. |
| `obj_type.database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `obj_type.database_column_mappings[].source_field` | `string` | Source field name. |
| `obj_type.database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `obj_type.database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `obj_type.database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `obj_type.database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `obj_type.automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `obj_type.automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `obj_type.automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `obj_type.automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `obj_type.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `obj_type.tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `obj_type.tags[].name` | `string` | The name of the namespace. |
| `obj_type.tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `obj_type.version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |

<a id="response"></a>

## Response: RefreshExternalObjectTypeColumnMappingsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `result` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | The definition as saved, with refreshed `database_column_mappings`. |
| `result.object_type` | [`ValueList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueList/index.md) | Basic data. |
| `result.object_type.id` | `int32` | The ID of the object type or value list. Object types and value lists share one ID space; property definition IDs and item IDs are separate spaces. |
| `result.object_type.name_singular` | `string` | The singular name, for example "Customer". Empty if the caller is not allowed to see the list. |
| `result.object_type.name_plural` | `string` | The plural name, for example "Customers". Empty if the caller is not allowed to see the list. |
| `result.object_type.icon` | `bytes` | The icon in .ICO format. Filled only by GetObjectTypes and GetObjectType, and only for real object types; empty in GetValueLists and GetValueList. |
| `result.object_type.is_real_object_type` | `bool` | True for an object type, whose items are objects (documents, customers); false for a plain value list (Country, Classes, Users). |
| `result.object_type.is_hierarchical` | `bool` | True if items can have a parent item in the same list (`ValueListItem.has_parent`). |
| `result.object_type.has_owner` | `bool` | True if every item belongs to an item of another list, the owner list (`owner_object_type`). For example, contact persons are owned by customers. |
| `result.object_type.owner_object_type` | `int32` | With `has_owner`, the ID of the owner list or object type. |
| `result.object_type.owner_property_def` | `int32` | Owner property def. Subobjects of objects of this object type have this property in their meta data for describing owner relationships. |
| `result.object_type.options` | [`OBJTYPEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md) | Flags of the list, for example `can_add_items` and `is_external`. See [OBJTYPEFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJTYPEFLAGS/index.md). |
| `result.object_type.default_property_def` | `int32` | The ID of the lookup property definition that refers to items of this list by default, for example 1079 (Customer) for the Customer object type. |
| `result.object_type.read_only_properties_during_insert[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the creation of a new object because they are not included in the INSERT INTO statement. |
| `result.object_type.read_only_properties_during_update[]` | repeated `int32` | The propertydef IDs of those properties that cannot be entered during the editing of an existing object because they are not included in the UPDATE statement. |
| `result.object_type.targets_for_browsing[]` | repeated [`ObjectTypeTargetForBrowsing`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeTargetForBrowsing/index.md) | Object type targets for browsing. |
| `result.object_type.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this object type. Also specifies who can add new items to this object type. |
| `result.object_type.object_type_permissions` | [`ObjectTypePermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypePermissionsForClient/index.md) | What the caller may do with the list: see it (`can_user_see`) and add items or objects (`can_user_add_new_items`). Filled by the read calls of IRPCObjectTypes and IRPCValueLists. |
| `result.object_type.default_acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Default ACL for new items/objects of this type. If unset, the global default is used (vlitems: read access to all internal users; real objects: full control for all internal users). |
| `result.object_type.vl_sorting_type_reserved` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `result.object_type.sort_ascending_reserved` | `bool` | True to sort in ascending order, false to sort in descending order. NOTE: This value is not currently used but is reserved for future use. Currently, sorting order is specified on the property definition level only. |
| `result.object_type.guid` | `string` | The GUID of the object type or value list, with braces. Resolve it to the vault's ID with [GetMetadataStructureItemIdByGUID](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureItemIdByGUID/index.md). |
| `result.object_type.preferred_title_property_def_id` | `int32` | Property definition ID of the title property for the user's preferred language. |
| `result.object_type.search_characteristics` | [`ObjectTypeSearchCharacteristics`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSearchCharacteristics/index.md) | If set, specifies search characteristics of the object type. |
| `result.object_type.indexing_definition` | [`ObjectTypeIndexingDefinition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeIndexingDefinition/index.md) | If set, defines the indexed value lists and properties of the object type. Used for searching from Master Storage. |
| `result.object_type.view_id` | `int32` | The ID of the object type specific view. |
| `result.database_connection_string` | `string` | OLE DB connection string to the external database that contains the objects (and their properties) of this object type. |
| `result.database_select_all_statement` | `string` | SQL statement that retrieves the objects from an external database. |
| `result.database_select_one_statement` | `string` | SQL statement that retrieves a specific object from an external database. |
| `result.database_insert_statement` | `string` | SQL statement that inserts a new object to an external database. |
| `result.database_select_latest_id_statement` | `string` | SQL statement that retrieves the ID of the just inserted record in the external database. |
| `result.database_update_statement` | `string` | SQL statement that updates an existing object in an external database. |
| `result.database_delete_statement` | `string` | SQL statement that deletes an object in an external database. |
| `result.database_column_mappings[]` | repeated [`ObjectTypeColumnMapping`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeColumnMapping/index.md) | Column mappings. |
| `result.database_column_mappings[].object_type` | `int32` | Object type ID. |
| `result.database_column_mappings[].ordinal` | `int32` | One-based source field ordinal. |
| `result.database_column_mappings[].source_field` | `string` | Source field name. |
| `result.database_column_mappings[].data_type` | `uint32` | Source field's data type. |
| `result.database_column_mappings[].target_property_def` | `int32` | Target property definition. |
| `result.database_column_mappings[].can_insert` | `bool` | Is the source field part of insertion operations? |
| `result.database_column_mappings[].can_update` | `bool` | Is the source field part of update operations? |
| `result.automatic_acl_for_objects` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | The default automatic permissions for items and objects. |
| `result.automatic_acl_for_objects.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `result.automatic_acl_for_objects.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `result.automatic_acl_for_objects.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `result.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `result.tags[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | Names value namespaces related to the object type. |
| `result.tags[].name` | `string` | The name of the namespace. |
| `result.tags[].values[]` | repeated [`NamedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValue/index.md) | Named value array related to the namespace. |
| `result.version_number` | `uint32` | Object type version number, used for OT modification conflicts tracking. |

<a id="related"></a>

## Related methods

- [GetObjectTypeDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/GetObjectTypeDef/index.md): Gets the full administrative definition of one object type or value list.
- [ParseSQLSelectStatement](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ParseSQLSelectStatement/index.md): Connects to an external database and returns the source table and columns of a SELECT statement, to set up the column mappings of an external object type.
- [ModifyObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/ModifyObjectType/index.md): Saves a changed definition of an object type or value list.

---

# IRPCObjectTypesAdmin.RemoveObjectType

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectType/

Badges: `Administration API / specialized` `admin` `session`

Removes an object type or value list together with its items, classes and dependent views.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/RemoveObjectType`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-object-type`
- **Request:** [`RemoveObjectTypeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectType/index.md#request)
- **Response:** [`RemoveObjectTypeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectType/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Destroys the list's items, the classes of the object type, the views and similar elements that
  use it, the external locations that create objects of the type, and the type's owner, default
  and conflict property definitions. This cannot be undone.
- Requires `change_metadata_structure` and `license_allows_modifications`.
- Fails for built-in object types and value lists, for a type or list that owns another one, for
  a real object type that still has objects (destroy them first), and when other property
  definitions are based on the list (the error names them).
- For an external object type only the cached items are removed; the external database is not
  touched.
- Increments the metadata structure version.

<a id="request"></a>

## Request: RemoveObjectTypeRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `object_type` | `int32` | The ID of the object type to remove. |

<a id="response"></a>

## Response: RemoveObjectTypeResponse

No fields.

<a id="related"></a>

## Related methods

- [RemoveObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md): Deletes an item of a value list as an administrator.

---

# IRPCObjectTypesAdmin.RemoveObjectTypeItem

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/

Badges: `Administration API / specialized` `admin` `session`

Deletes an item of a value list as an administrator.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-object-type-item`
- **Request:** [`RemoveObjectTypeItemRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md#request)
- **Response:** [`RemoveObjectTypeItemResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectTypeItem/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- The item is marked deleted. Only for plain value lists: real object types fail with
  "Not found.", classes (1), class groups (2) and list 18 with an invalid-argument error, and
  external lists are refused.
- If the item owns items in other lists, set `allow_removing_owned_items` to true to allow
  removing them as well.

<a id="request"></a>

## Request: RemoveObjectTypeItemRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The item: `type` is the value list ID, `item_id.internal_id` the item ID. |
| `obj_id.type` | `int32` | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
| `obj_id.item_id` | [`ItemID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemID/index.md) | The ID of the object within its type, in `item_id.internal_id`. |
| `obj_id.item_id.internal_id` | `int32` | The ID of the object or value list item. |
| `obj_id.item_id.external_repository_id` | [`ExternalRepositoryID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalRepositoryID/index.md) | Used only for objects in external repositories (external connectors). Leave it unset for objects stored in the vault. |
| `allow_removing_owned_items` | `bool` | True if removing the owned items of the object type item is allowed. The owned items reside in different object types. |

<a id="response"></a>

## Response: RemoveObjectTypeItemResponse

No fields.

<a id="related"></a>

## Related methods

- [RemoveObjectType](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/RemoveObjectType/index.md): Removes an object type or value list together with its items, classes and dependent views.

---

# IRPCObjectTypesAdmin.UpdateObjectTypeItem

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/UpdateObjectTypeItem/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Updates an item of a value list (for example its name, parent or owner) as an administrator.

- **Service:** [Object type administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md) `MFiles.IRPCObjectTypesAdmin`
- **gRPC method:** `/MFiles.IRPCObjectTypesAdmin/UpdateObjectTypeItem`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-object-type-item`
- **Request:** [`UpdateObjectTypeItemRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/UpdateObjectTypeItem/index.md#request)
- **Response:** [`UpdateObjectTypeItemResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/UpdateObjectTypeItem/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- The same list restrictions as
  [AddObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/index.md). The response is
  empty: read the item again to see the stored values.

<a id="request"></a>

## Request: UpdateObjectTypeItemRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `utf8szvlitem` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | The item with its new values; `item_info.obj_id` identifies it. |
| `utf8szvlitem.item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item. |
| `utf8szvlitem.item_info.obj_id` | [`ObjID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjID/index.md) | The object id or value list item id. Includes the object type or value list id. |
| `utf8szvlitem.item_info.name` | `string` | The name of the item. |
| `utf8szvlitem.item_info.external_id_status` | [`ExtIDStatus`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtIDStatus/index.md) | The status of this item's external ID. Values: `EXT_IDSTATUS_UNKNOWN` (0), `EXT_IDSTATUS_EXTERNAL` (1), `EXT_IDSTATUS_INTERNAL` (2), `EXT_IDSTATUS_DISCARDED` (3), `EXT_IDSTATUS_NOT_AVAILABLE` (4), `EXT_IDSTATUS_EXTERNAL_REDUCED` (5). |
| `utf8szvlitem.item_info.external_id` | `string` | The external ID (display ID) of this item. unset means that the external ID is the same as the internal ID. |
| `utf8szvlitem.item_info.guid` | `string` | GUID for the item. |
| `utf8szvlitem.item_info.options` | [`ITEMFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ITEMFLAGS/index.md) | Bit flags that provide additional information on the item (e.g. is the object deleted). |
| `utf8szvlitem.item_info.external_repository_icon_id` | `string` | The ID of the item's icon. |
| `utf8szvlitem.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `utf8szvlitem.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `utf8szvlitem.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `utf8szvlitem.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `utf8szvlitem.owner_name` | `string` | The name of the owner item. |
| `utf8szvlitem.automatic_permissions` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | If set, specifies the automatic permissions for an object for which the user selects this item. |
| `utf8szvlitem.automatic_permissions.permissions` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | The automatic permissions for an object for which the user selects this item. |
| `utf8szvlitem.automatic_permissions.is_default` | `bool` | True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type. |
| `utf8szvlitem.automatic_permissions.use_object_permissions` | `bool` | If true the object/item's own permissions are used as its automatic permissions. |
| `utf8szvlitem.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains the icon of this item in .ICO format. |
| `utf8szvlitem.icon.value` | `bytes` | Array of bytes. |

<a id="response"></a>

## Response: UpdateObjectTypeItemResponse

No fields.

<a id="related"></a>

## Related methods

- [AddObjectTypeItem](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/AddObjectTypeItem/index.md): Adds an item to a value list as an administrator.

---

# Property definition and class administration (IRPCPropertyDefsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/

Administers property definitions and classes: reads their full definitions, adds, modifies and
removes them, and starts recalculation of automatic values.

Use this interface to add, modify and remove property definitions.

- **gRPC service:** `MFiles.IRPCPropertyDefsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 14
- **Proto file:** [`mfiles/IRPCPropertyDefsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCPropertyDefsAdmin.proto)

<a id="overview"></a>

## Overview

This is the administrator's side of [IRPCPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md).
M-Files Admin and administrative tools call it; ordinary applications read property definitions
and classes with the Vault API instead.

| | Vault API (read side) | This service |
| --- | --- | --- |
| Property definitions | [GetPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/index.md): [PropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | [GetPropertyDefsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefsAdmin/index.md): [PropertyDefAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md), adding automatic value and validation settings and aliases |
| Classes | [GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md) | [GetObjectClasses](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses/index.md): [DocClass](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DocClass/index.md), with workflow, name property and aliases |
| Rights | none | see below |

- **Session and rights.** Every method requires a vault session. Writes need the vault rights
  `change_metadata_structure` and `license_allows_modifications`. Most reads need
  `read_all_metadata_structure`;
  [GetObjectClasses](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses/index.md) and
  [GetAssociatedPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetAssociatedPropertyDefs/index.md)
  need no vault rights. Setting or changing VBScript code needs a
  code-execution right (see [AddPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/index.md)).
- **Property definitions**:
  [GetPropertyDefsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefsAdmin/index.md),
  [GetPropertyDefAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefAdmin/index.md),
  [AddPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/index.md),
  [UpdatePropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdatePropertyDef/index.md),
  [RemovePropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemovePropertyDef/index.md),
  [GetLastUsedValue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetLastUsedValue/index.md),
  [IsPropertyFullTextSearchIndexable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/IsPropertyFullTextSearchIndexable/index.md).
- **Classes**:
  [GetObjectClasses](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses/index.md),
  [GetAssociatedPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetAssociatedPropertyDefs/index.md),
  [AddObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddObjectClass/index.md),
  [ModifyObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/ModifyObjectClass/index.md),
  [RemoveObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemoveObjectClass/index.md). Class groups
  are in [IRPCDocClassGroupsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md).
- **Update existing objects** (server-level jobs):
  [RecalculateProperty](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RecalculateProperty/index.md),
  [UpdateObjectNames](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdateObjectNames/index.md).

**Metadata structure version.** Adding, updating and removing a property definition increments both
`property_defs_version` and the vault's metadata structure version (see
[GetMetadataStructureVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVault/GetMetadataStructureVersion/index.md)); class
changes increment the metadata structure version.
The methods of this service do not send the `mfiles-metadata-version-bin` trailer.
See [Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddObjectClass/index.md) | Creates a class with its property associations. | `admin` `session` |
| [AddPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/index.md) | Creates a property definition. | `admin` `session` |
| [GetAssociatedPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetAssociatedPropertyDefs/index.md) | Gets the properties of a class: the property definitions associated with it and whether each is required. | `admin` `session` `idempotent` |
| [GetLastUsedValue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetLastUsedValue/index.md) | Gets the last number used by an automatic numbering property. | `admin` `session` `idempotent` |
| [GetObjectClasses](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses/index.md) | Gets the administrative definitions of all classes. | `admin` `session` `idempotent` |
| [GetPropertyDefAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefAdmin/index.md) | Gets the administrative definition of one property definition. | `admin` `session` |
| [GetPropertyDefsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefsAdmin/index.md) | Gets the administrative definitions of all property definitions. | `admin` `session` `idempotent` |
| [IsPropertyFullTextSearchIndexable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/IsPropertyFullTextSearchIndexable/index.md) | Tells whether the values of a property definition are indexed for full-text search. | `admin` `session` `idempotent` |
| [ModifyObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/ModifyObjectClass/index.md) | Saves a changed class and, optionally, its property associations. | `admin` `session` `idempotent` |
| [RecalculateProperty](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RecalculateProperty/index.md) | Starts a server job that recalculates the automatic values of a property in all existing objects. | `admin` `session` |
| [RemoveObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemoveObjectClass/index.md) | Deletes a class. | `admin` `session` |
| [RemovePropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemovePropertyDef/index.md) | Deletes a property definition and its values from all objects, or only counts the values that would be removed. | `admin` `session` |
| [UpdateObjectNames](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdateObjectNames/index.md) | Starts a server job that recalculates the names of all objects of a class from the class's name property. | `admin` `session` |
| [UpdatePropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdatePropertyDef/index.md) | Saves a changed property definition. | `admin` `session` `idempotent` |

---

# IRPCPropertyDefsAdmin.AddObjectClass

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddObjectClass/

Badges: `Administration API / specialized` `admin` `session`

Creates a class with its property associations.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/AddObjectClass`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-object-class`
- **Request:** [`AddObjectClassRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddObjectClass/index.md#request)
- **Response:** [`AddObjectClassResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddObjectClass/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- If the class's `name_property_def` is not Name or title (0), the server resets that property
  definition's permissions so that all users can see and edit it.
- Increments the metadata structure version.

<a id="request"></a>

## Request: AddObjectClassRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `doc_class` | [`DocClass`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DocClass/index.md) | The new class. The item ID and GUID in `value_list_item` are ignored and assigned by the server; `object_type` sets the object type of the class. |
| `doc_class.value_list_item` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | Value list item representing this document class. |
| `doc_class.value_list_item.item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item. |
| `doc_class.value_list_item.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `doc_class.value_list_item.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `doc_class.value_list_item.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `doc_class.value_list_item.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `doc_class.value_list_item.owner_name` | `string` | The name of the owner item. |
| `doc_class.value_list_item.automatic_permissions` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | If set, specifies the automatic permissions for an object for which the user selects this item. |
| `doc_class.value_list_item.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains the icon of this item in .ICO format. |
| `doc_class.workflow` | `int32` | The default workflow of the document class, or zero if there is no default workflow. |
| `doc_class.object_type` | `int32` | The object type with which this class is used. |
| `doc_class.is_predefined` | `bool` | True if this is a predefined class (cannot be deleted, editing is restricted). |
| `doc_class.force_workflow` | `bool` | True if the use of the workflow with this class is enforced. |
| `doc_class.name_property_def` | `int32` | The ID of the property definition that represents the name of the document or other object. Typically PROPERTYDEF_TITLE (0). |
| `doc_class.object_type_specific_properties` | [`ObjectTypeSpecificClassContentUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSpecificClassContentUnion/index.md) | Additional object type specific class content. |
| `doc_class.object_type_specific_properties.assignment` | [`AssignmentClassInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssignmentClassInfo/index.md) (oneof data) | Assignment-specific class settings. |
| `doc_class.signature_settings_for_new_objects` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | The electronic signature settings for creating an electronic signature for new objects. Reserved for future improvements. |
| `doc_class.signature_settings_for_new_objects.is_required` | `bool` | True if this transition requires an electronic signature. |
| `doc_class.signature_settings_for_new_objects.prompt_mode` | [`ElectronicSignaturePromptMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ElectronicSignaturePromptMode/index.md) | Option 1: static reason/meaning. Values: `ELECTRONIC_SIGNATURE_PROMPT_MODE_FIXED` (0), `ELECTRONIC_SIGNATURE_PROMPT_MODE_SELECTABLE` (1). |
| `doc_class.signature_settings_for_new_objects.fixed_prompt_details` | [`ElectronicSignaturePromptInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignaturePromptInfo/index.md) | Option 2: Pre-defined reason |
| `doc_class.signature_settings_for_new_objects.selectable_prompt_details[]` | repeated [`ElectronicSignaturePromptInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignaturePromptInfo/index.md) | Option 3: Metadata-based reason/meaning. |
| `doc_class.signature_settings_for_new_objects.user_selectable_reason_meaning_items_property_def` | `int32` | A property definition that represents items in value list. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `doc_class.signature_settings_for_new_objects.user_selectable_reason_property_def` | `int32` | A property definition that indicates the reason property. PROPERTYDEF_UNINITIALIZED if no reason is specified. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `doc_class.signature_settings_for_new_objects.user_selectable_meaning_property_def` | `int32` | A property definition that indicates the meaning property. PROPERTYDEF_UNINITIALIZED if no meaning is specified. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `doc_class.signature_settings_for_new_objects.add_metadata_reference_to_reason_meaning_item` | `bool` | Common prompt details. |
| `doc_class.signature_settings_for_new_objects.prompt_free_form_text` | `bool` | True if a free-form text is prompted with the signature. |
| `doc_class.signature_settings_for_new_objects.free_form_text_property_def` | `int32` | Signature details. boolean bFillReasonPropertyText;  //!< Optional? boolean bFillMeaningPropertyText;  //!< Optional? |
| `doc_class.signature_settings_for_new_objects.manifestation_additional_info` | `string` | Additional information for the manifestation text for the signature. This is not shown to the user when signing. |
| `doc_class.signature_settings_for_new_objects.create_separate_signature_object` | `bool` | True if the electronic signature shall be stored as a separate signature object. False to store as an embedded signature in a multi-line text property. |
| `doc_class.signature_settings_for_new_objects.manifestation_property_def` | `int32` | Property definition to be used for storing the signature manifestation on the object. Ignored if bCreateSeparateSignatureObject is true. |
| `doc_class.signature_settings_for_new_objects.signature_identifier` | `string` | Signature identifier. Required if bCreateSeparateSignatureObject is true. |
| `doc_class.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `property_defs[]` | repeated [`AssociatedPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) | The properties of the class and whether each is required. |
| `property_defs[].property_def` | `int32` | The ID of the property definition. |
| `property_defs[].is_required` | `bool` | True if objects of the class must have a value for this property. |

<a id="response"></a>

## Response: AddObjectClassResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new class. |

---

# IRPCPropertyDefsAdmin.AddPropertyDef

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/

Badges: `Administration API / specialized` `admin` `session`

Creates a property definition.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-property-def`
- **Request:** [`AddPropertyDefRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/index.md#request)
- **Response:** [`AddPropertyDefResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- VBScript code (automatic numbering or calculation with code, or validation with code) also
  requires the server right `run_code`; code with a valid signature needs only the vault right
  `run_signed_code`.
- `property_def.is_predefined` true, or an `update_type` other than `UPDATE_TYPE_NORMAL`, fails
  with an invalid-argument error.
- Increments `property_defs_version` and the metadata structure version.

<a id="request"></a>

## Request: AddPropertyDefRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `propdefadmin` | [`PropertyDefAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) | The new property definition. The ID (`property_def.id`) and GUID are ignored and assigned by the server. |
| `propdefadmin.property_def` | [`PropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | Basic data. |
| `propdefadmin.property_def.id` | `int32` | The property definition ID. Built-in property definitions (0 Name or title, 20 Created, 100 Class, ...) have the same ID in every vault. IDs 1-19 are never used by real property definitions. |
| `propdefadmin.property_def.name` | `string` | The name of the property. |
| `propdefadmin.property_def.tooltip` | `string` | The tip text of this property. |
| `propdefadmin.property_def.data_type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the values. Lookup properties use `DATATYPE_LOOKUP` (one item) or `DATATYPE_MULTI_SELECT_LOOKUP` (several items). |
| `propdefadmin.property_def.content_type` | [`ContentType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ContentType/index.md) | Content type (sub-datatype). Values: `CONTENT_TYPE_GENERIC` (0), `CONTENT_TYPE_EMAIL_ADDRESS` (1), `CONTENT_TYPE_URL` (2), `CONTENT_TYPE_RTF` (3), `CONTENT_TYPE_HTML` (4). |
| `propdefadmin.property_def.is_based_on_value_list` | `bool` | True for lookup properties; `value_list` then names the list. Test this flag, not `value_list != 0`: 0 is a valid list ID (the Document object type). |
| `propdefadmin.property_def.enable_automatic_permissions` | `bool` | True to allow automatic permissions via this property def. |
| `propdefadmin.property_def.is_conflict_reference` | `bool` | True if this is the conflict property of the object type in `value_list`. |
| `propdefadmin.property_def.disallow_as_grouping_level` | `bool` | True to disallow using this property def as a grouping level in views. |
| `propdefadmin.property_def.value_list` | `int32` | With `is_based_on_value_list`, the ID of the value list or object type whose items are the property's values. |
| `propdefadmin.property_def.value_list_item_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | A static filter on the items of `value_list`. The server applies it when this property is passed as `filtering_property_def` or `LookupItemRequest.property_def`; such conditions cannot be sent in `search_conditions` directly. |
| `propdefadmin.property_def.update_type` | [`UpdateType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UpdateType/index.md) | The update behaviour of the property. Values: `UPDATE_TYPE_NORMAL` (0), `UPDATE_TYPE_SET_BY_SERVER` (1), `UPDATE_TYPE_SET_BY_CLIENT_CODE` (2). |
| `propdefadmin.property_def.automatic_value_type` | [`AutomaticValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutomaticValueType/index.md) | Defines the type of the automatic value of this field, if any. Values: `AUTOMATIC_VALUE_TYPE_NONE` (0), `AUTOMATIC_VALUE_TYPE_CALCULATE_WITH_TEMPLATE` (1), `AUTOMATIC_VALUE_TYPE_CALCULATED_WITH_CODE` (2), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_INCREMENT` (3), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_CODE` (4). |
| `propdefadmin.property_def.default_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | If set, specifies a fixed default value for this property. |
| `propdefadmin.property_def.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains an icon in .ICO format (contains multiple sizes and color depths). |
| `propdefadmin.property_def.is_predefined` | `bool` | True if this is a predefined PropertyDef. Predefined PropertyDefs cannot be deleted and modifying them is restricted. |
| `propdefadmin.property_def.allow_for_all_object_types` | `bool` | True if this property definition can be used with all object types. |
| `propdefadmin.property_def.is_owner` | `bool` | True if this is the owner property of the object type in `value_list`. |
| `propdefadmin.property_def.is_default` | `bool` | True if this is the default property of the object type in `value_list` (`ValueList.default_property_def`). |
| `propdefadmin.property_def.owner_property_def_info` | [`OwnerPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OwnerPropertyDef/index.md) | For a lookup property, the property whose value limits this property's values. For example, Workflow State (39) is limited by Workflow (38). A `property_def` of -106 means that the owner property is determined automatically. |
| `propdefadmin.property_def.object_type` | `int32` | If `allow_for_all_object_types` is false, the object type whose objects use this property; otherwise ignored. |
| `propdefadmin.property_def.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, specifies the ACL that defines the visibility and editability of this property in objects. |
| `propdefadmin.property_def.property_def_permissions` | [`PropertyDefPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefPermissionsForClient/index.md) | What the caller may do with values of this property: see them and edit them. Set when the property definition has permissions. |
| `propdefadmin.property_def.value_list_sorting_type` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `propdefadmin.property_def.value_list_sort_ascending` | `bool` | True to sort in ascending order, false to sort in descending order. |
| `propdefadmin.property_def.validation_type` | [`ValidationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ValidationType/index.md) | How values are validated; `validation_string` holds the rule. Values: `VALIDATION_TYPE_NONE` (0), `VALIDATION_TYPE_REGEX` (1), `VALIDATION_TYPE_CODE` (2). |
| `propdefadmin.property_def.validation_string` | `string` | The validation rule; its meaning depends on `validation_type`. |
| `propdefadmin.property_def.formatting_type` | [`FormattingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FormattingType/index.md) | How values are formatted; `formatting_string` holds the format. Values: `FORMATTING_TYPE_NONE` (0). |
| `propdefadmin.property_def.formatting_string` | `string` | The format; its meaning depends on `formatting_type`. |
| `propdefadmin.property_def.guid` | `string` | The GUID of the property definition, with braces. |
| `propdefadmin.property_def.options` | [`PROPERTYDEFFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md) | Flags such as `can_use_in_search`. See [PROPERTYDEFFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md). |
| `propdefadmin.automatic_value` | [`AutomaticValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticValue/index.md) | The definitions for automatic value generation. |
| `propdefadmin.automatic_value.automatic_numbering_increment` | `int32` | Simple automatic numbering: Increment. |
| `propdefadmin.automatic_value.automatic_numbering_code` | `string` | Automatic numbering with VBScript: VBScript code. |
| `propdefadmin.automatic_value.calculated_value_template` | `string` | Simple calculated value: Expression. |
| `propdefadmin.automatic_value.calculated_value_code` | `string` | Calculated value with VBScript: VBScript code. |
| `propdefadmin.automatic_value.calculation_order` | `int32` | A number that specified calculation order. Properties are calculated from smallest to largest calculation order number. |
| `propdefadmin.validation` | [`Validation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Validation/index.md) | The definitions for property value validation. |
| `propdefadmin.validation.regular_expression` | `string` | A regular expression for the validation. |
| `propdefadmin.validation.code` | `string` | VBScript used in the validation. |
| `propdefadmin.aliases` | `string` | Semicolon-separated list of semantic aliases for metadata mapping. |
| `propdefadmin.tags` | [`NamedValueNamespaces`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespaces/index.md) | Names value namespaces related to the property definition. |
| `propdefadmin.tags.value[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | An array of the NamedValueNAmespace structures. |
| `reset_last_used_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | For an automatic numbering property, the number to continue from. Leave unset otherwise. |
| `reset_last_used_value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `reset_last_used_value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `reset_last_used_value.data` | [`TypedValueUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnion/index.md) | The value, in the member that matches `type`. Unset for an empty value. |
| `reset_last_used_value.data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `reset_last_used_value.data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `reset_last_used_value.data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `reset_last_used_value.data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `reset_last_used_value.data.date` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_DATE`: midnight UTC of the date. |
| `reset_last_used_value.data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `reset_last_used_value.data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `reset_last_used_value.data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `reset_last_used_value.data.lookup` | [`Lookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Lookup/index.md) (oneof data) | The value of `DATATYPE_LOOKUP`: one value list item or object. |
| `reset_last_used_value.data.multi_select_lookup` | [`MultiSelectLookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MultiSelectLookup/index.md) (oneof data) | The value of `DATATYPE_MULTI_SELECT_LOOKUP`: any number of value list items or objects. |
| `reset_last_used_value.data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `reset_last_used_value.data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `reset_last_used_value.data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `reset_last_used_value.data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |

<a id="response"></a>

## Response: AddPropertyDefResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `new_property_definition` | [`PropertyDefAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) | The property definition as stored, with its new ID. |
| `new_property_definition.property_def` | [`PropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | Basic data. |
| `new_property_definition.property_def.id` | `int32` | The property definition ID. Built-in property definitions (0 Name or title, 20 Created, 100 Class, ...) have the same ID in every vault. IDs 1-19 are never used by real property definitions. |
| `new_property_definition.property_def.name` | `string` | The name of the property. |
| `new_property_definition.property_def.tooltip` | `string` | The tip text of this property. |
| `new_property_definition.property_def.data_type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the values. Lookup properties use `DATATYPE_LOOKUP` (one item) or `DATATYPE_MULTI_SELECT_LOOKUP` (several items). |
| `new_property_definition.property_def.content_type` | [`ContentType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ContentType/index.md) | Content type (sub-datatype). Values: `CONTENT_TYPE_GENERIC` (0), `CONTENT_TYPE_EMAIL_ADDRESS` (1), `CONTENT_TYPE_URL` (2), `CONTENT_TYPE_RTF` (3), `CONTENT_TYPE_HTML` (4). |
| `new_property_definition.property_def.is_based_on_value_list` | `bool` | True for lookup properties; `value_list` then names the list. Test this flag, not `value_list != 0`: 0 is a valid list ID (the Document object type). |
| `new_property_definition.property_def.enable_automatic_permissions` | `bool` | True to allow automatic permissions via this property def. |
| `new_property_definition.property_def.is_conflict_reference` | `bool` | True if this is the conflict property of the object type in `value_list`. |
| `new_property_definition.property_def.disallow_as_grouping_level` | `bool` | True to disallow using this property def as a grouping level in views. |
| `new_property_definition.property_def.value_list` | `int32` | With `is_based_on_value_list`, the ID of the value list or object type whose items are the property's values. |
| `new_property_definition.property_def.value_list_item_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | A static filter on the items of `value_list`. The server applies it when this property is passed as `filtering_property_def` or `LookupItemRequest.property_def`; such conditions cannot be sent in `search_conditions` directly. |
| `new_property_definition.property_def.update_type` | [`UpdateType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UpdateType/index.md) | The update behaviour of the property. Values: `UPDATE_TYPE_NORMAL` (0), `UPDATE_TYPE_SET_BY_SERVER` (1), `UPDATE_TYPE_SET_BY_CLIENT_CODE` (2). |
| `new_property_definition.property_def.automatic_value_type` | [`AutomaticValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutomaticValueType/index.md) | Defines the type of the automatic value of this field, if any. Values: `AUTOMATIC_VALUE_TYPE_NONE` (0), `AUTOMATIC_VALUE_TYPE_CALCULATE_WITH_TEMPLATE` (1), `AUTOMATIC_VALUE_TYPE_CALCULATED_WITH_CODE` (2), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_INCREMENT` (3), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_CODE` (4). |
| `new_property_definition.property_def.default_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | If set, specifies a fixed default value for this property. |
| `new_property_definition.property_def.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains an icon in .ICO format (contains multiple sizes and color depths). |
| `new_property_definition.property_def.is_predefined` | `bool` | True if this is a predefined PropertyDef. Predefined PropertyDefs cannot be deleted and modifying them is restricted. |
| `new_property_definition.property_def.allow_for_all_object_types` | `bool` | True if this property definition can be used with all object types. |
| `new_property_definition.property_def.is_owner` | `bool` | True if this is the owner property of the object type in `value_list`. |
| `new_property_definition.property_def.is_default` | `bool` | True if this is the default property of the object type in `value_list` (`ValueList.default_property_def`). |
| `new_property_definition.property_def.owner_property_def_info` | [`OwnerPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OwnerPropertyDef/index.md) | For a lookup property, the property whose value limits this property's values. For example, Workflow State (39) is limited by Workflow (38). A `property_def` of -106 means that the owner property is determined automatically. |
| `new_property_definition.property_def.object_type` | `int32` | If `allow_for_all_object_types` is false, the object type whose objects use this property; otherwise ignored. |
| `new_property_definition.property_def.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, specifies the ACL that defines the visibility and editability of this property in objects. |
| `new_property_definition.property_def.property_def_permissions` | [`PropertyDefPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefPermissionsForClient/index.md) | What the caller may do with values of this property: see them and edit them. Set when the property definition has permissions. |
| `new_property_definition.property_def.value_list_sorting_type` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `new_property_definition.property_def.value_list_sort_ascending` | `bool` | True to sort in ascending order, false to sort in descending order. |
| `new_property_definition.property_def.validation_type` | [`ValidationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ValidationType/index.md) | How values are validated; `validation_string` holds the rule. Values: `VALIDATION_TYPE_NONE` (0), `VALIDATION_TYPE_REGEX` (1), `VALIDATION_TYPE_CODE` (2). |
| `new_property_definition.property_def.validation_string` | `string` | The validation rule; its meaning depends on `validation_type`. |
| `new_property_definition.property_def.formatting_type` | [`FormattingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FormattingType/index.md) | How values are formatted; `formatting_string` holds the format. Values: `FORMATTING_TYPE_NONE` (0). |
| `new_property_definition.property_def.formatting_string` | `string` | The format; its meaning depends on `formatting_type`. |
| `new_property_definition.property_def.guid` | `string` | The GUID of the property definition, with braces. |
| `new_property_definition.property_def.options` | [`PROPERTYDEFFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md) | Flags such as `can_use_in_search`. See [PROPERTYDEFFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md). |
| `new_property_definition.automatic_value` | [`AutomaticValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticValue/index.md) | The definitions for automatic value generation. |
| `new_property_definition.automatic_value.automatic_numbering_increment` | `int32` | Simple automatic numbering: Increment. |
| `new_property_definition.automatic_value.automatic_numbering_code` | `string` | Automatic numbering with VBScript: VBScript code. |
| `new_property_definition.automatic_value.calculated_value_template` | `string` | Simple calculated value: Expression. |
| `new_property_definition.automatic_value.calculated_value_code` | `string` | Calculated value with VBScript: VBScript code. |
| `new_property_definition.automatic_value.calculation_order` | `int32` | A number that specified calculation order. Properties are calculated from smallest to largest calculation order number. |
| `new_property_definition.validation` | [`Validation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Validation/index.md) | The definitions for property value validation. |
| `new_property_definition.validation.regular_expression` | `string` | A regular expression for the validation. |
| `new_property_definition.validation.code` | `string` | VBScript used in the validation. |
| `new_property_definition.aliases` | `string` | Semicolon-separated list of semantic aliases for metadata mapping. |
| `new_property_definition.tags` | [`NamedValueNamespaces`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespaces/index.md) | Names value namespaces related to the property definition. |
| `new_property_definition.tags.value[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | An array of the NamedValueNAmespace structures. |

---

# IRPCPropertyDefsAdmin.GetAssociatedPropertyDefs

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetAssociatedPropertyDefs/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the properties of a class: the property definitions associated with it and whether each is
required.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/GetAssociatedPropertyDefs`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-associated-property-defs`
- **Request:** [`GetAssociatedPropertyDefsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetAssociatedPropertyDefs/index.md#request)
- **Response:** [`GetAssociatedPropertyDefsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetAssociatedPropertyDefs/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session; no vault rights are needed.
- Class 0 returned 12 associations in the Sample Vault.

<a id="request"></a>

## Request: GetAssociatedPropertyDefsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `document_profile` | `int32` | The ID of the class. |

<a id="response"></a>

## Response: GetAssociatedPropertyDefsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`AssociatedPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) | One [AssociatedPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) per property of the class. |
| `values[].property_def` | `int32` | The ID of the property definition. |
| `values[].is_required` | `bool` | True if objects of the class must have a value for this property. |

---

# IRPCPropertyDefsAdmin.GetLastUsedValue

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetLastUsedValue/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the last number used by an automatic numbering property.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/GetLastUsedValue`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-last-used-value`
- **Request:** [`GetLastUsedValueRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetLastUsedValue/index.md#request)
- **Response:** [`GetLastUsedValueResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetLastUsedValue/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`.
- For a property definition without automatic numbering the value is empty (for example property 0).

<a id="request"></a>

## Request: GetLastUsedValueRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `property_def` | `int32` | The PropertyDef to get. |

<a id="response"></a>

## Response: GetLastUsedValueResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `last_used_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | Receives the result. |
| `last_used_value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `last_used_value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `last_used_value.data` | [`TypedValueUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnion/index.md) | The value, in the member that matches `type`. Unset for an empty value. |
| `last_used_value.data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `last_used_value.data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `last_used_value.data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `last_used_value.data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `last_used_value.data.date` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_DATE`: midnight UTC of the date. |
| `last_used_value.data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `last_used_value.data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `last_used_value.data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `last_used_value.data.lookup` | [`Lookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Lookup/index.md) (oneof data) | The value of `DATATYPE_LOOKUP`: one value list item or object. |
| `last_used_value.data.multi_select_lookup` | [`MultiSelectLookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MultiSelectLookup/index.md) (oneof data) | The value of `DATATYPE_MULTI_SELECT_LOOKUP`: any number of value list items or objects. |
| `last_used_value.data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `last_used_value.data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `last_used_value.data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `last_used_value.data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |

---

# IRPCPropertyDefsAdmin.GetObjectClasses

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the administrative definitions of all classes.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-object-classes`
- **Request:** [`GetObjectClassesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses/index.md#request)
- **Response:** [`GetObjectClassesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetObjectClasses/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session; no vault rights are needed. A normal user got all 41 classes of the
  Sample Vault, the same as an administrator.
- Names are in the session language. For class groups and the per-user permissions of classes,
  use [GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md).

<a id="request"></a>

## Request: GetObjectClassesRequest

No fields.

<a id="response"></a>

## Response: GetObjectClassesResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`DocClass`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DocClass/index.md) | One [DocClass](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DocClass/index.md) per class. The class ID is `value_list_item.item_info.obj_id.item_id.internal_id`. |
| `values[].value_list_item` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | Value list item representing this document class. |
| `values[].value_list_item.item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item. |
| `values[].value_list_item.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `values[].value_list_item.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `values[].value_list_item.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `values[].value_list_item.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `values[].value_list_item.owner_name` | `string` | The name of the owner item. |
| `values[].value_list_item.automatic_permissions` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | If set, specifies the automatic permissions for an object for which the user selects this item. |
| `values[].value_list_item.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains the icon of this item in .ICO format. |
| `values[].workflow` | `int32` | The default workflow of the document class, or zero if there is no default workflow. |
| `values[].object_type` | `int32` | The object type with which this class is used. |
| `values[].is_predefined` | `bool` | True if this is a predefined class (cannot be deleted, editing is restricted). |
| `values[].force_workflow` | `bool` | True if the use of the workflow with this class is enforced. |
| `values[].name_property_def` | `int32` | The ID of the property definition that represents the name of the document or other object. Typically PROPERTYDEF_TITLE (0). |
| `values[].object_type_specific_properties` | [`ObjectTypeSpecificClassContentUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSpecificClassContentUnion/index.md) | Additional object type specific class content. |
| `values[].object_type_specific_properties.assignment` | [`AssignmentClassInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssignmentClassInfo/index.md) (oneof data) | Assignment-specific class settings. |
| `values[].signature_settings_for_new_objects` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | The electronic signature settings for creating an electronic signature for new objects. Reserved for future improvements. |
| `values[].signature_settings_for_new_objects.is_required` | `bool` | True if this transition requires an electronic signature. |
| `values[].signature_settings_for_new_objects.prompt_mode` | [`ElectronicSignaturePromptMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ElectronicSignaturePromptMode/index.md) | Option 1: static reason/meaning. Values: `ELECTRONIC_SIGNATURE_PROMPT_MODE_FIXED` (0), `ELECTRONIC_SIGNATURE_PROMPT_MODE_SELECTABLE` (1). |
| `values[].signature_settings_for_new_objects.fixed_prompt_details` | [`ElectronicSignaturePromptInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignaturePromptInfo/index.md) | Option 2: Pre-defined reason |
| `values[].signature_settings_for_new_objects.selectable_prompt_details[]` | repeated [`ElectronicSignaturePromptInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignaturePromptInfo/index.md) | Option 3: Metadata-based reason/meaning. |
| `values[].signature_settings_for_new_objects.user_selectable_reason_meaning_items_property_def` | `int32` | A property definition that represents items in value list. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `values[].signature_settings_for_new_objects.user_selectable_reason_property_def` | `int32` | A property definition that indicates the reason property. PROPERTYDEF_UNINITIALIZED if no reason is specified. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `values[].signature_settings_for_new_objects.user_selectable_meaning_property_def` | `int32` | A property definition that indicates the meaning property. PROPERTYDEF_UNINITIALIZED if no meaning is specified. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `values[].signature_settings_for_new_objects.add_metadata_reference_to_reason_meaning_item` | `bool` | Common prompt details. |
| `values[].signature_settings_for_new_objects.prompt_free_form_text` | `bool` | True if a free-form text is prompted with the signature. |
| `values[].signature_settings_for_new_objects.free_form_text_property_def` | `int32` | Signature details. boolean bFillReasonPropertyText;  //!< Optional? boolean bFillMeaningPropertyText;  //!< Optional? |
| `values[].signature_settings_for_new_objects.manifestation_additional_info` | `string` | Additional information for the manifestation text for the signature. This is not shown to the user when signing. |
| `values[].signature_settings_for_new_objects.create_separate_signature_object` | `bool` | True if the electronic signature shall be stored as a separate signature object. False to store as an embedded signature in a multi-line text property. |
| `values[].signature_settings_for_new_objects.manifestation_property_def` | `int32` | Property definition to be used for storing the signature manifestation on the object. Ignored if bCreateSeparateSignatureObject is true. |
| `values[].signature_settings_for_new_objects.signature_identifier` | `string` | Signature identifier. Required if bCreateSeparateSignatureObject is true. |
| `values[].aliases` | `string` | Semicolon-separated list of semantic aliases. |

<a id="related"></a>

## Related methods

- [IRPCPropertyDefs.GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md): Gets all classes and class groups that the user is allowed to see.

---

# IRPCPropertyDefsAdmin.GetPropertyDefAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefAdmin/

Badges: `Administration API / specialized` `admin` `session`

Gets the administrative definition of one property definition.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-property-def-admin`
- **Request:** [`GetPropertyDefAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefAdmin/index.md#request)
- **Response:** [`GetPropertyDefAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
- An unknown ID fails with `Unknown property definition "<id>".`.

<a id="request"></a>

## Request: GetPropertyDefAdminRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `property_def` | `int32` | The ID of the property definition. |

<a id="response"></a>

## Response: GetPropertyDefAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `ppropdefadmin` | [`PropertyDefAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) | The definition. See [PropertyDefAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md). |
| `ppropdefadmin.property_def` | [`PropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | Basic data. |
| `ppropdefadmin.property_def.id` | `int32` | The property definition ID. Built-in property definitions (0 Name or title, 20 Created, 100 Class, ...) have the same ID in every vault. IDs 1-19 are never used by real property definitions. |
| `ppropdefadmin.property_def.name` | `string` | The name of the property. |
| `ppropdefadmin.property_def.tooltip` | `string` | The tip text of this property. |
| `ppropdefadmin.property_def.data_type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the values. Lookup properties use `DATATYPE_LOOKUP` (one item) or `DATATYPE_MULTI_SELECT_LOOKUP` (several items). |
| `ppropdefadmin.property_def.content_type` | [`ContentType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ContentType/index.md) | Content type (sub-datatype). Values: `CONTENT_TYPE_GENERIC` (0), `CONTENT_TYPE_EMAIL_ADDRESS` (1), `CONTENT_TYPE_URL` (2), `CONTENT_TYPE_RTF` (3), `CONTENT_TYPE_HTML` (4). |
| `ppropdefadmin.property_def.is_based_on_value_list` | `bool` | True for lookup properties; `value_list` then names the list. Test this flag, not `value_list != 0`: 0 is a valid list ID (the Document object type). |
| `ppropdefadmin.property_def.enable_automatic_permissions` | `bool` | True to allow automatic permissions via this property def. |
| `ppropdefadmin.property_def.is_conflict_reference` | `bool` | True if this is the conflict property of the object type in `value_list`. |
| `ppropdefadmin.property_def.disallow_as_grouping_level` | `bool` | True to disallow using this property def as a grouping level in views. |
| `ppropdefadmin.property_def.value_list` | `int32` | With `is_based_on_value_list`, the ID of the value list or object type whose items are the property's values. |
| `ppropdefadmin.property_def.value_list_item_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | A static filter on the items of `value_list`. The server applies it when this property is passed as `filtering_property_def` or `LookupItemRequest.property_def`; such conditions cannot be sent in `search_conditions` directly. |
| `ppropdefadmin.property_def.update_type` | [`UpdateType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UpdateType/index.md) | The update behaviour of the property. Values: `UPDATE_TYPE_NORMAL` (0), `UPDATE_TYPE_SET_BY_SERVER` (1), `UPDATE_TYPE_SET_BY_CLIENT_CODE` (2). |
| `ppropdefadmin.property_def.automatic_value_type` | [`AutomaticValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutomaticValueType/index.md) | Defines the type of the automatic value of this field, if any. Values: `AUTOMATIC_VALUE_TYPE_NONE` (0), `AUTOMATIC_VALUE_TYPE_CALCULATE_WITH_TEMPLATE` (1), `AUTOMATIC_VALUE_TYPE_CALCULATED_WITH_CODE` (2), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_INCREMENT` (3), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_CODE` (4). |
| `ppropdefadmin.property_def.default_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | If set, specifies a fixed default value for this property. |
| `ppropdefadmin.property_def.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains an icon in .ICO format (contains multiple sizes and color depths). |
| `ppropdefadmin.property_def.is_predefined` | `bool` | True if this is a predefined PropertyDef. Predefined PropertyDefs cannot be deleted and modifying them is restricted. |
| `ppropdefadmin.property_def.allow_for_all_object_types` | `bool` | True if this property definition can be used with all object types. |
| `ppropdefadmin.property_def.is_owner` | `bool` | True if this is the owner property of the object type in `value_list`. |
| `ppropdefadmin.property_def.is_default` | `bool` | True if this is the default property of the object type in `value_list` (`ValueList.default_property_def`). |
| `ppropdefadmin.property_def.owner_property_def_info` | [`OwnerPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OwnerPropertyDef/index.md) | For a lookup property, the property whose value limits this property's values. For example, Workflow State (39) is limited by Workflow (38). A `property_def` of -106 means that the owner property is determined automatically. |
| `ppropdefadmin.property_def.object_type` | `int32` | If `allow_for_all_object_types` is false, the object type whose objects use this property; otherwise ignored. |
| `ppropdefadmin.property_def.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, specifies the ACL that defines the visibility and editability of this property in objects. |
| `ppropdefadmin.property_def.property_def_permissions` | [`PropertyDefPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefPermissionsForClient/index.md) | What the caller may do with values of this property: see them and edit them. Set when the property definition has permissions. |
| `ppropdefadmin.property_def.value_list_sorting_type` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `ppropdefadmin.property_def.value_list_sort_ascending` | `bool` | True to sort in ascending order, false to sort in descending order. |
| `ppropdefadmin.property_def.validation_type` | [`ValidationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ValidationType/index.md) | How values are validated; `validation_string` holds the rule. Values: `VALIDATION_TYPE_NONE` (0), `VALIDATION_TYPE_REGEX` (1), `VALIDATION_TYPE_CODE` (2). |
| `ppropdefadmin.property_def.validation_string` | `string` | The validation rule; its meaning depends on `validation_type`. |
| `ppropdefadmin.property_def.formatting_type` | [`FormattingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FormattingType/index.md) | How values are formatted; `formatting_string` holds the format. Values: `FORMATTING_TYPE_NONE` (0). |
| `ppropdefadmin.property_def.formatting_string` | `string` | The format; its meaning depends on `formatting_type`. |
| `ppropdefadmin.property_def.guid` | `string` | The GUID of the property definition, with braces. |
| `ppropdefadmin.property_def.options` | [`PROPERTYDEFFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md) | Flags such as `can_use_in_search`. See [PROPERTYDEFFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md). |
| `ppropdefadmin.automatic_value` | [`AutomaticValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticValue/index.md) | The definitions for automatic value generation. |
| `ppropdefadmin.automatic_value.automatic_numbering_increment` | `int32` | Simple automatic numbering: Increment. |
| `ppropdefadmin.automatic_value.automatic_numbering_code` | `string` | Automatic numbering with VBScript: VBScript code. |
| `ppropdefadmin.automatic_value.calculated_value_template` | `string` | Simple calculated value: Expression. |
| `ppropdefadmin.automatic_value.calculated_value_code` | `string` | Calculated value with VBScript: VBScript code. |
| `ppropdefadmin.automatic_value.calculation_order` | `int32` | A number that specified calculation order. Properties are calculated from smallest to largest calculation order number. |
| `ppropdefadmin.validation` | [`Validation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Validation/index.md) | The definitions for property value validation. |
| `ppropdefadmin.validation.regular_expression` | `string` | A regular expression for the validation. |
| `ppropdefadmin.validation.code` | `string` | VBScript used in the validation. |
| `ppropdefadmin.aliases` | `string` | Semicolon-separated list of semantic aliases for metadata mapping. |
| `ppropdefadmin.tags` | [`NamedValueNamespaces`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespaces/index.md) | Names value namespaces related to the property definition. |
| `ppropdefadmin.tags.value[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | An array of the NamedValueNAmespace structures. |

---

# IRPCPropertyDefsAdmin.GetPropertyDefsAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefsAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the administrative definitions of all property definitions.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefsAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-property-defs-admin`
- **Request:** [`GetPropertyDefsAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefsAdmin/index.md#request)
- **Response:** [`GetPropertyDefsAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefsAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.". Users
  without the right call [GetPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/index.md).
- Returned 150 property definitions in the Sample Vault, built-in ones included.

<a id="request"></a>

## Request: GetPropertyDefsAdminRequest

No fields.

<a id="response"></a>

## Response: GetPropertyDefsAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`PropertyDefAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) | One [PropertyDefAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) per property definition. |
| `values[].property_def` | [`PropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | Basic data. |
| `values[].property_def.id` | `int32` | The property definition ID. Built-in property definitions (0 Name or title, 20 Created, 100 Class, ...) have the same ID in every vault. IDs 1-19 are never used by real property definitions. |
| `values[].property_def.name` | `string` | The name of the property. |
| `values[].property_def.tooltip` | `string` | The tip text of this property. |
| `values[].property_def.data_type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the values. Lookup properties use `DATATYPE_LOOKUP` (one item) or `DATATYPE_MULTI_SELECT_LOOKUP` (several items). |
| `values[].property_def.content_type` | [`ContentType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ContentType/index.md) | Content type (sub-datatype). Values: `CONTENT_TYPE_GENERIC` (0), `CONTENT_TYPE_EMAIL_ADDRESS` (1), `CONTENT_TYPE_URL` (2), `CONTENT_TYPE_RTF` (3), `CONTENT_TYPE_HTML` (4). |
| `values[].property_def.is_based_on_value_list` | `bool` | True for lookup properties; `value_list` then names the list. Test this flag, not `value_list != 0`: 0 is a valid list ID (the Document object type). |
| `values[].property_def.enable_automatic_permissions` | `bool` | True to allow automatic permissions via this property def. |
| `values[].property_def.is_conflict_reference` | `bool` | True if this is the conflict property of the object type in `value_list`. |
| `values[].property_def.disallow_as_grouping_level` | `bool` | True to disallow using this property def as a grouping level in views. |
| `values[].property_def.value_list` | `int32` | With `is_based_on_value_list`, the ID of the value list or object type whose items are the property's values. |
| `values[].property_def.value_list_item_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | A static filter on the items of `value_list`. The server applies it when this property is passed as `filtering_property_def` or `LookupItemRequest.property_def`; such conditions cannot be sent in `search_conditions` directly. |
| `values[].property_def.update_type` | [`UpdateType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UpdateType/index.md) | The update behaviour of the property. Values: `UPDATE_TYPE_NORMAL` (0), `UPDATE_TYPE_SET_BY_SERVER` (1), `UPDATE_TYPE_SET_BY_CLIENT_CODE` (2). |
| `values[].property_def.automatic_value_type` | [`AutomaticValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutomaticValueType/index.md) | Defines the type of the automatic value of this field, if any. Values: `AUTOMATIC_VALUE_TYPE_NONE` (0), `AUTOMATIC_VALUE_TYPE_CALCULATE_WITH_TEMPLATE` (1), `AUTOMATIC_VALUE_TYPE_CALCULATED_WITH_CODE` (2), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_INCREMENT` (3), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_CODE` (4). |
| `values[].property_def.default_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | If set, specifies a fixed default value for this property. |
| `values[].property_def.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains an icon in .ICO format (contains multiple sizes and color depths). |
| `values[].property_def.is_predefined` | `bool` | True if this is a predefined PropertyDef. Predefined PropertyDefs cannot be deleted and modifying them is restricted. |
| `values[].property_def.allow_for_all_object_types` | `bool` | True if this property definition can be used with all object types. |
| `values[].property_def.is_owner` | `bool` | True if this is the owner property of the object type in `value_list`. |
| `values[].property_def.is_default` | `bool` | True if this is the default property of the object type in `value_list` (`ValueList.default_property_def`). |
| `values[].property_def.owner_property_def_info` | [`OwnerPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OwnerPropertyDef/index.md) | For a lookup property, the property whose value limits this property's values. For example, Workflow State (39) is limited by Workflow (38). A `property_def` of -106 means that the owner property is determined automatically. |
| `values[].property_def.object_type` | `int32` | If `allow_for_all_object_types` is false, the object type whose objects use this property; otherwise ignored. |
| `values[].property_def.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, specifies the ACL that defines the visibility and editability of this property in objects. |
| `values[].property_def.property_def_permissions` | [`PropertyDefPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefPermissionsForClient/index.md) | What the caller may do with values of this property: see them and edit them. Set when the property definition has permissions. |
| `values[].property_def.value_list_sorting_type` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `values[].property_def.value_list_sort_ascending` | `bool` | True to sort in ascending order, false to sort in descending order. |
| `values[].property_def.validation_type` | [`ValidationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ValidationType/index.md) | How values are validated; `validation_string` holds the rule. Values: `VALIDATION_TYPE_NONE` (0), `VALIDATION_TYPE_REGEX` (1), `VALIDATION_TYPE_CODE` (2). |
| `values[].property_def.validation_string` | `string` | The validation rule; its meaning depends on `validation_type`. |
| `values[].property_def.formatting_type` | [`FormattingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FormattingType/index.md) | How values are formatted; `formatting_string` holds the format. Values: `FORMATTING_TYPE_NONE` (0). |
| `values[].property_def.formatting_string` | `string` | The format; its meaning depends on `formatting_type`. |
| `values[].property_def.guid` | `string` | The GUID of the property definition, with braces. |
| `values[].property_def.options` | [`PROPERTYDEFFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md) | Flags such as `can_use_in_search`. See [PROPERTYDEFFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md). |
| `values[].automatic_value` | [`AutomaticValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticValue/index.md) | The definitions for automatic value generation. |
| `values[].automatic_value.automatic_numbering_increment` | `int32` | Simple automatic numbering: Increment. |
| `values[].automatic_value.automatic_numbering_code` | `string` | Automatic numbering with VBScript: VBScript code. |
| `values[].automatic_value.calculated_value_template` | `string` | Simple calculated value: Expression. |
| `values[].automatic_value.calculated_value_code` | `string` | Calculated value with VBScript: VBScript code. |
| `values[].automatic_value.calculation_order` | `int32` | A number that specified calculation order. Properties are calculated from smallest to largest calculation order number. |
| `values[].validation` | [`Validation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Validation/index.md) | The definitions for property value validation. |
| `values[].validation.regular_expression` | `string` | A regular expression for the validation. |
| `values[].validation.code` | `string` | VBScript used in the validation. |
| `values[].aliases` | `string` | Semicolon-separated list of semantic aliases for metadata mapping. |
| `values[].tags` | [`NamedValueNamespaces`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespaces/index.md) | Names value namespaces related to the property definition. |
| `values[].tags.value[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | An array of the NamedValueNAmespace structures. |

<a id="related"></a>

## Related methods

- [IRPCPropertyDefs.GetPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetPropertyDefs/index.md): Gets all property definitions that the user is allowed to see.

---

# IRPCPropertyDefsAdmin.IsPropertyFullTextSearchIndexable

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/IsPropertyFullTextSearchIndexable/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Tells whether the values of a property definition are indexed for full-text search.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/IsPropertyFullTextSearchIndexable`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/is-property-full-text-search-indexable`
- **Request:** [`IsPropertyFullTextSearchIndexableRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/IsPropertyFullTextSearchIndexable/index.md#request)
- **Response:** [`IsPropertyFullTextSearchIndexableResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/IsPropertyFullTextSearchIndexable/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
- Name or title (0) returned true.

<a id="request"></a>

## Request: IsPropertyFullTextSearchIndexableRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `property_def` | `int32` | The PropertyDef to get information on. |

<a id="response"></a>

## Response: IsPropertyFullTextSearchIndexableResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `indexable` | `bool` | Receives true if indexable, false otherwise. |

---

# IRPCPropertyDefsAdmin.ModifyObjectClass

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/ModifyObjectClass/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Saves a changed class and, optionally, its property associations.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/ModifyObjectClass`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-object-class`
- **Request:** [`ModifyObjectClassRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/ModifyObjectClass/index.md#request)
- **Response:** [`ModifyObjectClassResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/ModifyObjectClass/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
  class.
- Adding or removing properties of existing objects runs as background tasks, returned in
  `async_task_ids`; follow them with
  [GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md).
- The same name-property permission rule as in
  [AddObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddObjectClass/index.md) applies.
- Increments the metadata structure version.

<a id="request"></a>

## Request: ModifyObjectClassRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `doc_class` | [`DocClass`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DocClass/index.md) | The complete new class; `value_list_item.item_info.obj_id.item_id.internal_id` identifies it. |
| `doc_class.value_list_item` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | Value list item representing this document class. |
| `doc_class.value_list_item.item_info` | [`ItemInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemInfo/index.md) | The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item. |
| `doc_class.value_list_item.has_parent` | `bool` | True if the item has a parent item in the same (hierarchical) list. |
| `doc_class.value_list_item.has_owner` | `bool` | True if the item belongs to an item of the owner list (`ValueList.owner_object_type`). |
| `doc_class.value_list_item.parent_id` | `int32` | With `has_parent`, the item ID of the parent item; otherwise ignored. |
| `doc_class.value_list_item.owner_id` | `int32` | With `has_owner`, the item ID of the owner item in the owner list. |
| `doc_class.value_list_item.owner_name` | `string` | The name of the owner item. |
| `doc_class.value_list_item.automatic_permissions` | [`AutomaticPermissions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticPermissions/index.md) | If set, specifies the automatic permissions for an object for which the user selects this item. |
| `doc_class.value_list_item.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains the icon of this item in .ICO format. |
| `doc_class.workflow` | `int32` | The default workflow of the document class, or zero if there is no default workflow. |
| `doc_class.object_type` | `int32` | The object type with which this class is used. |
| `doc_class.is_predefined` | `bool` | True if this is a predefined class (cannot be deleted, editing is restricted). |
| `doc_class.force_workflow` | `bool` | True if the use of the workflow with this class is enforced. |
| `doc_class.name_property_def` | `int32` | The ID of the property definition that represents the name of the document or other object. Typically PROPERTYDEF_TITLE (0). |
| `doc_class.object_type_specific_properties` | [`ObjectTypeSpecificClassContentUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeSpecificClassContentUnion/index.md) | Additional object type specific class content. |
| `doc_class.object_type_specific_properties.assignment` | [`AssignmentClassInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssignmentClassInfo/index.md) (oneof data) | Assignment-specific class settings. |
| `doc_class.signature_settings_for_new_objects` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | The electronic signature settings for creating an electronic signature for new objects. Reserved for future improvements. |
| `doc_class.signature_settings_for_new_objects.is_required` | `bool` | True if this transition requires an electronic signature. |
| `doc_class.signature_settings_for_new_objects.prompt_mode` | [`ElectronicSignaturePromptMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ElectronicSignaturePromptMode/index.md) | Option 1: static reason/meaning. Values: `ELECTRONIC_SIGNATURE_PROMPT_MODE_FIXED` (0), `ELECTRONIC_SIGNATURE_PROMPT_MODE_SELECTABLE` (1). |
| `doc_class.signature_settings_for_new_objects.fixed_prompt_details` | [`ElectronicSignaturePromptInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignaturePromptInfo/index.md) | Option 2: Pre-defined reason |
| `doc_class.signature_settings_for_new_objects.selectable_prompt_details[]` | repeated [`ElectronicSignaturePromptInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignaturePromptInfo/index.md) | Option 3: Metadata-based reason/meaning. |
| `doc_class.signature_settings_for_new_objects.user_selectable_reason_meaning_items_property_def` | `int32` | A property definition that represents items in value list. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `doc_class.signature_settings_for_new_objects.user_selectable_reason_property_def` | `int32` | A property definition that indicates the reason property. PROPERTYDEF_UNINITIALIZED if no reason is specified. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `doc_class.signature_settings_for_new_objects.user_selectable_meaning_property_def` | `int32` | A property definition that indicates the meaning property. PROPERTYDEF_UNINITIALIZED if no meaning is specified. Used if the prompt mode is eesrmpmPromptModeMetadataBasedUserSelectable. |
| `doc_class.signature_settings_for_new_objects.add_metadata_reference_to_reason_meaning_item` | `bool` | Common prompt details. |
| `doc_class.signature_settings_for_new_objects.prompt_free_form_text` | `bool` | True if a free-form text is prompted with the signature. |
| `doc_class.signature_settings_for_new_objects.free_form_text_property_def` | `int32` | Signature details. boolean bFillReasonPropertyText;  //!< Optional? boolean bFillMeaningPropertyText;  //!< Optional? |
| `doc_class.signature_settings_for_new_objects.manifestation_additional_info` | `string` | Additional information for the manifestation text for the signature. This is not shown to the user when signing. |
| `doc_class.signature_settings_for_new_objects.create_separate_signature_object` | `bool` | True if the electronic signature shall be stored as a separate signature object. False to store as an embedded signature in a multi-line text property. |
| `doc_class.signature_settings_for_new_objects.manifestation_property_def` | `int32` | Property definition to be used for storing the signature manifestation on the object. Ignored if bCreateSeparateSignatureObject is true. |
| `doc_class.signature_settings_for_new_objects.signature_identifier` | `string` | Signature identifier. Required if bCreateSeparateSignatureObject is true. |
| `doc_class.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `automatic_permissions_forced_active` | `bool` | True to make changed automatic permissions active on the objects of the class, false to add them inactive. |
| `modify_associations` | `bool` | True to replace the class's property associations with `property_defs`. |
| `property_defs[]` | repeated [`AssociatedPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) | The new property associations. Ignored when `modify_associations` is false. |
| `property_defs[].property_def` | `int32` | The ID of the property definition. |
| `property_defs[].is_required` | `bool` | True if objects of the class must have a value for this property. |

<a id="response"></a>

## Response: ModifyObjectClassResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_idchange_objects` | `int64` | The ID of the last background task that adds or removes properties of existing objects, or -1 if there is none. It is also in `async_task_ids`. |
| `async_task_ids[]` | repeated [`AsyncTaskID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTaskID/index.md) | All background tasks started by the change. |
| `async_task_ids[].id` | `int64` | Task ID. |
| `async_task_ids[].type` | `string` | Task type name. |
| `async_task_ids[].definition` | `string` | The display string of the task definition. |

<a id="related"></a>

## Related methods

- [IRPCBackgroundOperationsAdmin.GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md): Gets one asynchronous task by ID.
- [AddObjectClass](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddObjectClass/index.md): Creates a class with its property associations.

---

# IRPCPropertyDefsAdmin.RecalculateProperty

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RecalculateProperty/

Badges: `Administration API / specialized` `admin` `session`

Starts a server job that recalculates the automatic values of a property in all existing objects.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/RecalculateProperty`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/recalculate-property`
- **Request:** [`RecalculatePropertyRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RecalculateProperty/index.md#request)
- **Response:** [`RecalculatePropertyResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RecalculateProperty/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Starts a temporary server-level scheduled job and returns before it completes. `task_id` is the
  job's ID; M-Files Admin follows it with
  [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md) from a
  server-level session.
- Changes property values of existing objects. Requires `change_metadata_structure` and
  `license_allows_modifications`.

<a id="request"></a>

## Request: RecalculatePropertyRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `property_def` | `int32` | The ID of the property to recalculate. |
| `null_values_only` | `bool` | True to fill in only empty values, false to recalculate every value. |

<a id="response"></a>

## Response: RecalculatePropertyResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the scheduled job that does the work. |

<a id="related"></a>

## Related methods

- [IRPCScheduledJobsAdmin.GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md): Gets the run state of a scheduled job: running or not, last and next run, errors and progress.

---

# IRPCPropertyDefsAdmin.RemoveObjectClass

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemoveObjectClass/

Badges: `Administration API / specialized` `admin` `session`

Deletes a class.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/RemoveObjectClass`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-object-class`
- **Request:** [`RemoveObjectClassRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemoveObjectClass/index.md#request)
- **Response:** [`RemoveObjectClassResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemoveObjectClass/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
  class.
- Built-in classes cannot be removed.
- Objects of the class may exist: the class is then only marked deleted, new objects cannot use
  it, and existing objects keep their property values.
- Removes the class from its class groups. Increments the metadata structure version.

<a id="request"></a>

## Request: RemoveObjectClassRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `class_id` | `int32` | The ID of the object class to remove. |

<a id="response"></a>

## Response: RemoveObjectClassResponse

No fields.

---

# IRPCPropertyDefsAdmin.RemovePropertyDef

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemovePropertyDef/

Badges: `Administration API / specialized` `admin` `session`

Deletes a property definition and its values from all objects, or only counts the values that
would be removed.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/RemovePropertyDef`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-property-def`
- **Request:** [`RemovePropertyDefRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemovePropertyDef/index.md#request)
- **Response:** [`RemovePropertyDefResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/RemovePropertyDef/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- With `check_effects_only` false: **deletes all values of the property from the vault**, and the
  views and similar elements that use it. Use `copy_to_another_property_def` to move the values
  to another property definition first. This cannot be undone.
- With `check_effects_only` true: changes nothing and returns the counts in `null_values` and
  `non_null_values`. Otherwise both counts are 0.
- Requires `change_metadata_structure` and `license_allows_modifications`.
- Built-in property definitions cannot be removed. A property definition used by classes fails
  with an error that names the classes, unless `delete_from_classes_if_necessary` is true.
- Increments `property_defs_version` and the metadata structure version.

<a id="request"></a>

## Request: RemovePropertyDefRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `property_def` | `int32` | The ID of the PropertyDef to remove. |
| `copy_to_another_property_def` | `bool` | True to move the values to `target_property_def` before deleting. |
| `target_property_def` | `int32` | The property definition that receives the values. Used only when `copy_to_another_property_def` is true. |
| `append` | `bool` | True to add the moved values to the target's existing values, false to overwrite them. |
| `delete_from_classes_if_necessary` | `bool` | True to remove the property definition from the classes that use it; false to fail if any class uses it. |
| `check_effects_only` | `bool` | True if the server should only check the effects of these changes to existing documents and not apply the changes yet. |

<a id="response"></a>

## Response: RemovePropertyDefResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `null_values` | `uint32` | With `check_effects_only`, the number of empty values that would be removed. |
| `non_null_values` | `uint32` | With `check_effects_only`, the number of non-empty values that would be removed. |

---

# IRPCPropertyDefsAdmin.UpdateObjectNames

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdateObjectNames/

Badges: `Administration API / specialized` `admin` `session`

Starts a server job that recalculates the names of all objects of a class from the class's name
property.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/UpdateObjectNames`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-object-names`
- **Request:** [`UpdateObjectNamesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdateObjectNames/index.md#request)
- **Response:** [`UpdateObjectNamesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdateObjectNames/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Starts a temporary server-level scheduled job and returns before it completes. `task_id` is the
  job's ID; M-Files Admin follows it with
  [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md) from a
  server-level session.
- Requires `change_metadata_structure` and `license_allows_modifications`.
- Fails with an invalid-argument error when the class uses Name or title (property 0) as its name
  property: there is nothing to recalculate.

<a id="request"></a>

## Request: UpdateObjectNamesRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `doc_class` | `int32` | The ID of the class whose objects are renamed. |

<a id="response"></a>

## Response: UpdateObjectNamesResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_id` | `int32` | The ID of the scheduled job that does the work. |

<a id="related"></a>

## Related methods

- [IRPCScheduledJobsAdmin.GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md): Gets the run state of a scheduled job: running or not, last and next run, errors and progress.

---

# IRPCPropertyDefsAdmin.UpdatePropertyDef

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdatePropertyDef/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Saves a changed property definition.

- **Service:** [Property definition and class administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md) `MFiles.IRPCPropertyDefsAdmin`
- **gRPC method:** `/MFiles.IRPCPropertyDefsAdmin/UpdatePropertyDef`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-property-def`
- **Request:** [`UpdatePropertyDefRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdatePropertyDef/index.md#request)
- **Response:** [`UpdatePropertyDefResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/UpdatePropertyDef/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`, plus the code rights
  described in [AddPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/index.md) when VBScript
  code is set or changed.
- `data_type`, `is_based_on_value_list`, `value_list` and `update_type` cannot change: send them
  exactly as stored.
- Applying changed automatic permissions to existing objects runs as background tasks, returned
  in `async_task_ids`; follow them with
  [GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md).
- Increments `property_defs_version` and the metadata structure version.

<a id="request"></a>

## Request: UpdatePropertyDefRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `propdefadmin` | [`PropertyDefAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) | The complete new definition; `property_def.id` identifies it. Start from [GetPropertyDefAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/GetPropertyDefAdmin/index.md). |
| `propdefadmin.property_def` | [`PropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDef/index.md) | Basic data. |
| `propdefadmin.property_def.id` | `int32` | The property definition ID. Built-in property definitions (0 Name or title, 20 Created, 100 Class, ...) have the same ID in every vault. IDs 1-19 are never used by real property definitions. |
| `propdefadmin.property_def.name` | `string` | The name of the property. |
| `propdefadmin.property_def.tooltip` | `string` | The tip text of this property. |
| `propdefadmin.property_def.data_type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the values. Lookup properties use `DATATYPE_LOOKUP` (one item) or `DATATYPE_MULTI_SELECT_LOOKUP` (several items). |
| `propdefadmin.property_def.content_type` | [`ContentType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ContentType/index.md) | Content type (sub-datatype). Values: `CONTENT_TYPE_GENERIC` (0), `CONTENT_TYPE_EMAIL_ADDRESS` (1), `CONTENT_TYPE_URL` (2), `CONTENT_TYPE_RTF` (3), `CONTENT_TYPE_HTML` (4). |
| `propdefadmin.property_def.is_based_on_value_list` | `bool` | True for lookup properties; `value_list` then names the list. Test this flag, not `value_list != 0`: 0 is a valid list ID (the Document object type). |
| `propdefadmin.property_def.enable_automatic_permissions` | `bool` | True to allow automatic permissions via this property def. |
| `propdefadmin.property_def.is_conflict_reference` | `bool` | True if this is the conflict property of the object type in `value_list`. |
| `propdefadmin.property_def.disallow_as_grouping_level` | `bool` | True to disallow using this property def as a grouping level in views. |
| `propdefadmin.property_def.value_list` | `int32` | With `is_based_on_value_list`, the ID of the value list or object type whose items are the property's values. |
| `propdefadmin.property_def.value_list_item_filter[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | A static filter on the items of `value_list`. The server applies it when this property is passed as `filtering_property_def` or `LookupItemRequest.property_def`; such conditions cannot be sent in `search_conditions` directly. |
| `propdefadmin.property_def.update_type` | [`UpdateType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.UpdateType/index.md) | The update behaviour of the property. Values: `UPDATE_TYPE_NORMAL` (0), `UPDATE_TYPE_SET_BY_SERVER` (1), `UPDATE_TYPE_SET_BY_CLIENT_CODE` (2). |
| `propdefadmin.property_def.automatic_value_type` | [`AutomaticValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutomaticValueType/index.md) | Defines the type of the automatic value of this field, if any. Values: `AUTOMATIC_VALUE_TYPE_NONE` (0), `AUTOMATIC_VALUE_TYPE_CALCULATE_WITH_TEMPLATE` (1), `AUTOMATIC_VALUE_TYPE_CALCULATED_WITH_CODE` (2), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_INCREMENT` (3), `AUTOMATIC_VALUE_TYPE_FIXED_VALUE_WITH_CODE` (4). |
| `propdefadmin.property_def.default_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | If set, specifies a fixed default value for this property. |
| `propdefadmin.property_def.icon` | [`Bytes`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Bytes/index.md) | If set, contains an icon in .ICO format (contains multiple sizes and color depths). |
| `propdefadmin.property_def.is_predefined` | `bool` | True if this is a predefined PropertyDef. Predefined PropertyDefs cannot be deleted and modifying them is restricted. |
| `propdefadmin.property_def.allow_for_all_object_types` | `bool` | True if this property definition can be used with all object types. |
| `propdefadmin.property_def.is_owner` | `bool` | True if this is the owner property of the object type in `value_list`. |
| `propdefadmin.property_def.is_default` | `bool` | True if this is the default property of the object type in `value_list` (`ValueList.default_property_def`). |
| `propdefadmin.property_def.owner_property_def_info` | [`OwnerPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OwnerPropertyDef/index.md) | For a lookup property, the property whose value limits this property's values. For example, Workflow State (39) is limited by Workflow (38). A `property_def` of -106 means that the owner property is determined automatically. |
| `propdefadmin.property_def.object_type` | `int32` | If `allow_for_all_object_types` is false, the object type whose objects use this property; otherwise ignored. |
| `propdefadmin.property_def.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | If set, specifies the ACL that defines the visibility and editability of this property in objects. |
| `propdefadmin.property_def.property_def_permissions` | [`PropertyDefPermissionsForClient`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefPermissionsForClient/index.md) | What the caller may do with values of this property: see them and edit them. Set when the property definition has permissions. |
| `propdefadmin.property_def.value_list_sorting_type` | [`VLSortingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.VLSortingType/index.md) | The sorting type of value list items. Values: `VLSORTING_TYPE_BY_DISPLAY_NAME` (0), `VLSORTING_TYPE_BY_EXTERNAL_ID` (1). |
| `propdefadmin.property_def.value_list_sort_ascending` | `bool` | True to sort in ascending order, false to sort in descending order. |
| `propdefadmin.property_def.validation_type` | [`ValidationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ValidationType/index.md) | How values are validated; `validation_string` holds the rule. Values: `VALIDATION_TYPE_NONE` (0), `VALIDATION_TYPE_REGEX` (1), `VALIDATION_TYPE_CODE` (2). |
| `propdefadmin.property_def.validation_string` | `string` | The validation rule; its meaning depends on `validation_type`. |
| `propdefadmin.property_def.formatting_type` | [`FormattingType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.FormattingType/index.md) | How values are formatted; `formatting_string` holds the format. Values: `FORMATTING_TYPE_NONE` (0). |
| `propdefadmin.property_def.formatting_string` | `string` | The format; its meaning depends on `formatting_type`. |
| `propdefadmin.property_def.guid` | `string` | The GUID of the property definition, with braces. |
| `propdefadmin.property_def.options` | [`PROPERTYDEFFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md) | Flags such as `can_use_in_search`. See [PROPERTYDEFFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PROPERTYDEFFLAGS/index.md). |
| `propdefadmin.automatic_value` | [`AutomaticValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AutomaticValue/index.md) | The definitions for automatic value generation. |
| `propdefadmin.automatic_value.automatic_numbering_increment` | `int32` | Simple automatic numbering: Increment. |
| `propdefadmin.automatic_value.automatic_numbering_code` | `string` | Automatic numbering with VBScript: VBScript code. |
| `propdefadmin.automatic_value.calculated_value_template` | `string` | Simple calculated value: Expression. |
| `propdefadmin.automatic_value.calculated_value_code` | `string` | Calculated value with VBScript: VBScript code. |
| `propdefadmin.automatic_value.calculation_order` | `int32` | A number that specified calculation order. Properties are calculated from smallest to largest calculation order number. |
| `propdefadmin.validation` | [`Validation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Validation/index.md) | The definitions for property value validation. |
| `propdefadmin.validation.regular_expression` | `string` | A regular expression for the validation. |
| `propdefadmin.validation.code` | `string` | VBScript used in the validation. |
| `propdefadmin.aliases` | `string` | Semicolon-separated list of semantic aliases for metadata mapping. |
| `propdefadmin.tags` | [`NamedValueNamespaces`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespaces/index.md) | Names value namespaces related to the property definition. |
| `propdefadmin.tags.value[]` | repeated [`NamedValueNamespace`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedValueNamespace/index.md) | An array of the NamedValueNAmespace structures. |
| `reset_last_used_value` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | For an automatic numbering property, the number to continue from. Leave unset to keep the current one. |
| `reset_last_used_value.is_null_value` | `bool` | True if the value is empty. `data` is then unset. |
| `reset_last_used_value.type` | [`Datatype`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.Datatype/index.md) | The data type of the value. |
| `reset_last_used_value.data` | [`TypedValueUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValueUnion/index.md) | The value, in the member that matches `type`. Unset for an empty value. |
| `reset_last_used_value.data.text` | `string` (oneof data) | The value of `DATATYPE_TEXT`. |
| `reset_last_used_value.data.integer` | `int32` (oneof data) | The value of `DATATYPE_INTEGER`. |
| `reset_last_used_value.data.real_number` | `double` (oneof data) | The value of `DATATYPE_REAL_NUMBER`. |
| `reset_last_used_value.data.decimal_number` | `string` (oneof data) | Fixed precision number. |
| `reset_last_used_value.data.date` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_DATE`: midnight UTC of the date. |
| `reset_last_used_value.data.time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | Time. |
| `reset_last_used_value.data.timestamp` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | The value of `DATATYPE_TIMESTAMP`, in UTC. |
| `reset_last_used_value.data.boolean` | `bool` (oneof data) | The value of `DATATYPE_BOOLEAN`. |
| `reset_last_used_value.data.lookup` | [`Lookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Lookup/index.md) (oneof data) | The value of `DATATYPE_LOOKUP`: one value list item or object. |
| `reset_last_used_value.data.multi_select_lookup` | [`MultiSelectLookup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MultiSelectLookup/index.md) (oneof data) | The value of `DATATYPE_MULTI_SELECT_LOOKUP`: any number of value list items or objects. |
| `reset_last_used_value.data.integer64` | `int64` (oneof data) | Integer (8 bytes). |
| `reset_last_used_value.data.filetime` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) (oneof data) | FILETIME (64-bit integer). |
| `reset_last_used_value.data.multi_line_text` | `string` (oneof data) | The value of `DATATYPE_MULTI_LINE_TEXT`. |
| `reset_last_used_value.data.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (oneof data) | Access Control List. |
| `automatic_permissions_forced_active` | `bool` | Used only when the change turns on automatic permissions: true to make them active on existing objects, false to add them inactive. |

<a id="response"></a>

## Response: UpdatePropertyDefResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `async_task_ids[]` | repeated [`AsyncTaskID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTaskID/index.md) | Asynchronous task identifiers, if any, related to the change. |
| `async_task_ids[].id` | `int64` | Task ID. |
| `async_task_ids[].type` | `string` | Task type name. |
| `async_task_ids[].definition` | `string` | The display string of the task definition. |

<a id="related"></a>

## Related methods

- [AddPropertyDef](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/AddPropertyDef/index.md): Creates a property definition.
- [IRPCBackgroundOperationsAdmin.GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md): Gets one asynchronous task by ID.

---

# Class groups (IRPCDocClassGroupsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/

Administers class groups: reads, adds, modifies and removes the groups that organize document
classes.

Use this interface to add, modify and delete document class groups in a vault.

- **gRPC service:** `MFiles.IRPCDocClassGroupsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 4
- **Proto file:** [`mfiles/IRPCDocClassGroupsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCDocClassGroupsAdmin.proto)

<a id="overview"></a>

## Overview

A class group bundles document classes. Class groups are items of the built-in value list 2.
M-Files Admin calls this service; applications read class groups with
[GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md), which
needs no special rights and also returns the classes with the caller's permissions.

- **Session and rights.** Every method requires a vault session.
  [GetDocClassGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/GetDocClassGroups/index.md) needs the vault
  right `read_all_metadata_structure` (a normal user gets "Access denied."). The write
  methods need `change_metadata_structure` and `license_allows_modifications`.
- **Calls**: [GetDocClassGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/GetDocClassGroups/index.md),
  [AddDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup/index.md),
  [ModifyDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/ModifyDocClassGroup/index.md),
  [RemoveDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/RemoveDocClassGroup/index.md). The classes
  themselves are in [IRPCPropertyDefsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefsAdmin/index.md); value list 2
  cannot be edited with the item methods of
  [IRPCObjectTypesAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypesAdmin/index.md).
- **Metadata structure version.** Every successful add, modify and remove increments the vault's metadata
  version when it commits. The methods do not send the `mfiles-metadata-version-bin` trailer;
  see [Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup/index.md) | Creates a class group. | `admin` `session` |
| [GetDocClassGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/GetDocClassGroups/index.md) | Gets all class groups with their member classes. | `admin` `session` `idempotent` |
| [ModifyDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/ModifyDocClassGroup/index.md) | Saves a changed class group: its name and member classes. | `admin` `session` `idempotent` |
| [RemoveDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/RemoveDocClassGroup/index.md) | Deletes a class group. | `admin` `session` |

---

# IRPCDocClassGroupsAdmin.AddDocClassGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup/

Badges: `Administration API / specialized` `admin` `session`

Creates a class group.

- **Service:** [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md) `MFiles.IRPCDocClassGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-doc-class-group`
- **Request:** [`AddDocClassGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup/index.md#request)
- **Response:** [`AddDocClassGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`.
- Only document classes can be grouped: `object_type` must be 0 (Document), otherwise the call
  fails with an invalid-argument error.
- Increments the metadata structure version.

<a id="request"></a>

## Request: AddDocClassGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `class_group` | [`ClassGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) | The new [ClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) with its name and member classes. `id` is ignored and assigned by the server. |
| `class_group.id` | `int32` | The ID of the class group (an item ID in value list 2, Class groups). |
| `class_group.name` | `string` | The name of the group. |
| `class_group.member_classes[]` | repeated `int32` | The IDs of the classes in the group. |
| `class_group.object_type` | `int32` | The object type with which this class group is used. |

<a id="response"></a>

## Response: AddDocClassGroupResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new class group. |

---

# IRPCDocClassGroupsAdmin.GetDocClassGroups

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/GetDocClassGroups/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all class groups with their member classes.

- **Service:** [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md) `MFiles.IRPCDocClassGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCDocClassGroupsAdmin/GetDocClassGroups`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-doc-class-groups`
- **Request:** [`GetDocClassGroupsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/GetDocClassGroups/index.md#request)
- **Response:** [`GetDocClassGroupsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/GetDocClassGroups/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
  Without that right, use
  [GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md).
- Returned 7 groups in the Sample Vault. The order is undefined.

<a id="request"></a>

## Request: GetDocClassGroupsRequest

No fields.

<a id="response"></a>

## Response: GetDocClassGroupsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `class_groups[]` | repeated [`ClassGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) | One [ClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) per class group. |
| `class_groups[].id` | `int32` | The ID of the class group (an item ID in value list 2, Class groups). |
| `class_groups[].name` | `string` | The name of the group. |
| `class_groups[].member_classes[]` | repeated `int32` | The IDs of the classes in the group. |
| `class_groups[].object_type` | `int32` | The object type with which this class group is used. |

<a id="related"></a>

## Related methods

- [IRPCPropertyDefs.GetObjectClassesAndGroups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/GetObjectClassesAndGroups/index.md): Gets all classes and class groups that the user is allowed to see.

---

# IRPCDocClassGroupsAdmin.ModifyDocClassGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/ModifyDocClassGroup/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Saves a changed class group: its name and member classes.

- **Service:** [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md) `MFiles.IRPCDocClassGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCDocClassGroupsAdmin/ModifyDocClassGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-doc-class-group`
- **Request:** [`ModifyDocClassGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/ModifyDocClassGroup/index.md#request)
- **Response:** [`ModifyDocClassGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/ModifyDocClassGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
  group. `object_type` must be 0 (Document), as in
  [AddDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup/index.md).
- Classes added to or removed from `member_classes` change the class-group information of
  existing documents of those classes.
- Increments the metadata structure version.

<a id="request"></a>

## Request: ModifyDocClassGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `class_group` | [`ClassGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) | The complete new [ClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md); `id` identifies the group to modify. |
| `class_group.id` | `int32` | The ID of the class group (an item ID in value list 2, Class groups). |
| `class_group.name` | `string` | The name of the group. |
| `class_group.member_classes[]` | repeated `int32` | The IDs of the classes in the group. |
| `class_group.object_type` | `int32` | The object type with which this class group is used. |

<a id="response"></a>

## Response: ModifyDocClassGroupResponse

No fields.

<a id="related"></a>

## Related methods

- [AddDocClassGroup](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/AddDocClassGroup/index.md): Creates a class group.

---

# IRPCDocClassGroupsAdmin.RemoveDocClassGroup

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/RemoveDocClassGroup/

Badges: `Administration API / specialized` `admin` `session`

Deletes a class group.

- **Service:** [Class groups](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/index.md) `MFiles.IRPCDocClassGroupsAdmin`
- **gRPC method:** `/MFiles.IRPCDocClassGroupsAdmin/RemoveDocClassGroup`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-doc-class-group`
- **Request:** [`RemoveDocClassGroupRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/RemoveDocClassGroup/index.md#request)
- **Response:** [`RemoveDocClassGroupResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDocClassGroupsAdmin/RemoveDocClassGroup/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `change_metadata_structure` and `license_allows_modifications`, and read access to the
  group.
- The member classes are not deleted. Existing documents of those classes are updated so that
  they no longer refer to the group.
- Increments the metadata structure version.

<a id="request"></a>

## Request: RemoveDocClassGroupRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the class group to delete. |

<a id="response"></a>

## Response: RemoveDocClassGroupResponse

No fields.

---

# Workflow administration (IRPCWorkflowsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/

Administers workflows: reads their full definitions with states and transitions, and adds,
modifies and removes them.

Use this interface to add, modify and delete workflows in a vault.

- **gRPC service:** `MFiles.IRPCWorkflowsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 5
- **Proto file:** [`mfiles/IRPCWorkflowsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCWorkflowsAdmin.proto)

<a id="overview"></a>

## Overview

This is the administrator's side of workflows. M-Files Admin calls it; applications that move
objects through workflows read them with
[GetWorkflowsForClient](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowsForClient/index.md) and
[GetWorkflowStatesAndTransitions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectOperations/GetWorkflowStatesAndTransitions/index.md),
which need no special rights and return what the caller may do (see
[Workflows](https://developer.m-files.com/APIs/gRPC-API/concepts/workflows/index.md)).

| | Vault API (read side) | This service |
| --- | --- | --- |
| Data | names, states and the transitions the user may take | [WorkflowAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md): states with their actions and conditions, transitions with their permissions, triggers and signatures, the workflow ACL, aliases and diagram layout |
| Rights | none | `read_all_metadata_structure` to read, `manage_workflows` to write |

- **Session and rights.** Every method requires a vault session.
  [GetWorkflows](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/index.md) needs the vault right
  `read_all_metadata_structure` (a normal user gets "Access denied."). The write methods
  need `manage_workflows` and `license_allows_modifications`. Setting or changing VBScript code in
  states and transitions also needs a code-execution right (see
  [AddWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/index.md)).
- **Calls**: [GetWorkflows](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/index.md), then
  [AddWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/index.md) or
  [ModifyWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/ModifyWorkflow/index.md) with a complete
  [WorkflowAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md), and
  [RemoveWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow/index.md) or
  [RemoveWorkflows](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflows/index.md).
- **New states and transitions** get negative placeholder IDs in the request (-1, -2, ...);
  transitions refer to new states by these placeholders. The response contains the workflow as
  stored, with real IDs.
- **Metadata structure version.** Every successful add, modify and remove increments the vault's metadata
  version when it commits; clients that cache workflows reload them. The methods do not send the
  `mfiles-metadata-version-bin` trailer; see
  [Metadata structure version and caching](https://developer.m-files.com/APIs/gRPC-API/concepts/metadata-structure-version-and-caching/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/index.md) | Creates a workflow with its states and transitions. | `admin` `session` |
| [GetWorkflows](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/index.md) | Gets the full administrative definitions of all workflows. | `admin` `session` |
| [ModifyWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/ModifyWorkflow/index.md) | Saves a changed workflow with its states and transitions. | `admin` `session` |
| [RemoveWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow/index.md) | Deletes a workflow with its states and transitions. | `admin` `session` |
| [RemoveWorkflows](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflows/index.md) | Deletes several workflows in one transaction. | `admin` `session` |

---

# IRPCWorkflowsAdmin.AddWorkflow

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/

Badges: `Administration API / specialized` `admin` `session`

Creates a workflow with its states and transitions.

- **Service:** [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md) `MFiles.IRPCWorkflowsAdmin`
- **gRPC method:** `/MFiles.IRPCWorkflowsAdmin/AddWorkflow`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-workflow`
- **Request:** [`AddWorkflowRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/index.md#request)
- **Response:** [`AddWorkflowResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `manage_workflows` and `license_allows_modifications`.
- VBScript code in states (actions, pre- and postconditions) and transitions also requires the
  server right `run_code`; code with a valid signature needs only the vault right
  `run_signed_code`.
- The session language must be the vault's default language; otherwise the call fails with
  "Not implemented.".
- Fails when another workflow has the same name (case-insensitive).
- Increments the metadata structure version.

<a id="request"></a>

## Request: AddWorkflowRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `workflow` | [`WorkflowAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) | The new workflow. `workflow.workflow.id` is ignored; give the states and transitions negative placeholder IDs. |
| `workflow.workflow` | [`Workflow`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Workflow/index.md) | Basic information on the workflow. |
| `workflow.workflow.id` | `int32` | Workflow ID. |
| `workflow.workflow.name` | `string` | The name of the workflow. |
| `workflow.workflow.object_class_id` | `int32` | The class this workflow can be used with. |
| `workflow.workflow.description` | `string` | The user description of the workflow. |
| `workflow.workflow.reserved1_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow.workflow.reserved2_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow.description` | `string` | The description of the workflow. |
| `workflow.states[]` | repeated [`State`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.State/index.md) | The states of this workflow. |
| `workflow.states[].id` | `int32` | State ID. |
| `workflow.states[].name` | `string` | The name of the state. |
| `workflow.states[].description` | `string` | The description of the state. |
| `workflow.states[].options` | [`ACTIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACTIONFLAGS/index.md) | Flags that tell which actions are enabled for this state. |
| `workflow.states[].action_set_acl` | [`ActionSetACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetACL/index.md) | The properties of the Set Permissions action. |
| `workflow.states[].action_assign_to_user` | [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | The properties of the Assign to User action. |
| `workflow.states[].actions[]` | repeated [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | Action array. |
| `workflow.states[].action_send_notification` | [`ActionSendNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSendNotification/index.md) | The properties of the Send Notification action. |
| `workflow.states[].action_set_properties` | [`ActionSetProperties`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetProperties/index.md) | Action: set properties. |
| `workflow.states[].action_convert_to_pdf` | [`ActionConvertToPDF`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionConvertToPDF/index.md) | Action: convert to PDF. |
| `workflow.states[].action_code` | `string` | Action: run VBScript code. |
| `workflow.states[].restrict_transitions` | `bool` | True if transitions involving this state must be individually allowed. |
| `workflow.states[].transitions_require_edit_access_to_object` | `bool` | True if state transitions require edit access to the object. |
| `workflow.states[].check_in_out_acl` | `bool` | True if the in/out permissions of this state should be checked. |
| `workflow.states[].in_out_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The in/out permissions of this state. |
| `workflow.states[].preconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State preconditions. (rules) |
| `workflow.states[].postconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State postconditions. (rules) |
| `workflow.states[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow.states[].user_description` | `string` | The user description of the state. |
| `workflow.states[].state_flags` | [`STATEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.STATEFLAGS/index.md) | Flags that tell different options set for this state. |
| `workflow.states[].agent_action_guid` | `string` | The agent action GUID of the state, or GUID_NULL if not set. |
| `workflow.transitions[]` | repeated [`StateTransition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransition/index.md) | The state transitions of this workflow. |
| `workflow.transitions[].id` | `int32` | State transition ID. |
| `workflow.transitions[].from_state` | `int32` | The source state. |
| `workflow.transitions[].to_state` | `int32` | The target state. |
| `workflow.transitions[].evaluation_order` | `int32` | The evaluation order. |
| `workflow.transitions[].name` | `string` | The name of the state. |
| `workflow.transitions[].description` | `string` | The description of the state. |
| `workflow.transitions[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Transition permissions. |
| `workflow.transitions[].signature_settings` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | Signature settings for this state transition. |
| `workflow.transitions[].trigger_mode` | [`AutoStateTransitionMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutoStateTransitionMode/index.md) | The selected mode for automatically triggered state transition. Values: `AUTO_STATE_TRANSITION_MODE_NONE` (0), `AUTO_STATE_TRANSITION_MODE_RELATIVE_TIME` (1), `AUTO_STATE_TRANSITION_MODE_CRITERIA_FULFILLED` (4), `AUTO_STATE_TRANSITION_MODE_SCRIPT_FULFILLED` (5), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_COMPLETE` (6), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_REJECTED` (7). |
| `workflow.transitions[].trigger_in_days` | `uint32` | The number of days before automatically triggered state transition. |
| `workflow.transitions[].trigger_criteria[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The criteria for automatically triggered state transition. |
| `workflow.transitions[].trigger_code` | `string` | The VB script for automatically triggered state transition. |
| `workflow.transitions[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow.transitions[].vault_guids[]` | repeated `string` | An array of GUIDS of vaults where this state transition will be triggered. |
| `workflow.transitions[].user_description` | `string` | The user description of the state. |
| `workflow.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `workflow.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `workflow.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `workflow.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `workflow.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `workflow.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `workflow.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `workflow.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow.graphical_layout_data` | `string` | Layout data of the workflow. |

<a id="response"></a>

## Response: AddWorkflowResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `workflow_result` | [`WorkflowAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) | The workflow as stored, with real IDs for the workflow, its states and its transitions. |
| `workflow_result.workflow` | [`Workflow`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Workflow/index.md) | Basic information on the workflow. |
| `workflow_result.workflow.id` | `int32` | Workflow ID. |
| `workflow_result.workflow.name` | `string` | The name of the workflow. |
| `workflow_result.workflow.object_class_id` | `int32` | The class this workflow can be used with. |
| `workflow_result.workflow.description` | `string` | The user description of the workflow. |
| `workflow_result.workflow.reserved1_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow_result.workflow.reserved2_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow_result.description` | `string` | The description of the workflow. |
| `workflow_result.states[]` | repeated [`State`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.State/index.md) | The states of this workflow. |
| `workflow_result.states[].id` | `int32` | State ID. |
| `workflow_result.states[].name` | `string` | The name of the state. |
| `workflow_result.states[].description` | `string` | The description of the state. |
| `workflow_result.states[].options` | [`ACTIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACTIONFLAGS/index.md) | Flags that tell which actions are enabled for this state. |
| `workflow_result.states[].action_set_acl` | [`ActionSetACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetACL/index.md) | The properties of the Set Permissions action. |
| `workflow_result.states[].action_assign_to_user` | [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | The properties of the Assign to User action. |
| `workflow_result.states[].actions[]` | repeated [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | Action array. |
| `workflow_result.states[].action_send_notification` | [`ActionSendNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSendNotification/index.md) | The properties of the Send Notification action. |
| `workflow_result.states[].action_set_properties` | [`ActionSetProperties`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetProperties/index.md) | Action: set properties. |
| `workflow_result.states[].action_convert_to_pdf` | [`ActionConvertToPDF`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionConvertToPDF/index.md) | Action: convert to PDF. |
| `workflow_result.states[].action_code` | `string` | Action: run VBScript code. |
| `workflow_result.states[].restrict_transitions` | `bool` | True if transitions involving this state must be individually allowed. |
| `workflow_result.states[].transitions_require_edit_access_to_object` | `bool` | True if state transitions require edit access to the object. |
| `workflow_result.states[].check_in_out_acl` | `bool` | True if the in/out permissions of this state should be checked. |
| `workflow_result.states[].in_out_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The in/out permissions of this state. |
| `workflow_result.states[].preconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State preconditions. (rules) |
| `workflow_result.states[].postconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State postconditions. (rules) |
| `workflow_result.states[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_result.states[].user_description` | `string` | The user description of the state. |
| `workflow_result.states[].state_flags` | [`STATEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.STATEFLAGS/index.md) | Flags that tell different options set for this state. |
| `workflow_result.states[].agent_action_guid` | `string` | The agent action GUID of the state, or GUID_NULL if not set. |
| `workflow_result.transitions[]` | repeated [`StateTransition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransition/index.md) | The state transitions of this workflow. |
| `workflow_result.transitions[].id` | `int32` | State transition ID. |
| `workflow_result.transitions[].from_state` | `int32` | The source state. |
| `workflow_result.transitions[].to_state` | `int32` | The target state. |
| `workflow_result.transitions[].evaluation_order` | `int32` | The evaluation order. |
| `workflow_result.transitions[].name` | `string` | The name of the state. |
| `workflow_result.transitions[].description` | `string` | The description of the state. |
| `workflow_result.transitions[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Transition permissions. |
| `workflow_result.transitions[].signature_settings` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | Signature settings for this state transition. |
| `workflow_result.transitions[].trigger_mode` | [`AutoStateTransitionMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutoStateTransitionMode/index.md) | The selected mode for automatically triggered state transition. Values: `AUTO_STATE_TRANSITION_MODE_NONE` (0), `AUTO_STATE_TRANSITION_MODE_RELATIVE_TIME` (1), `AUTO_STATE_TRANSITION_MODE_CRITERIA_FULFILLED` (4), `AUTO_STATE_TRANSITION_MODE_SCRIPT_FULFILLED` (5), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_COMPLETE` (6), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_REJECTED` (7). |
| `workflow_result.transitions[].trigger_in_days` | `uint32` | The number of days before automatically triggered state transition. |
| `workflow_result.transitions[].trigger_criteria[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The criteria for automatically triggered state transition. |
| `workflow_result.transitions[].trigger_code` | `string` | The VB script for automatically triggered state transition. |
| `workflow_result.transitions[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_result.transitions[].vault_guids[]` | repeated `string` | An array of GUIDS of vaults where this state transition will be triggered. |
| `workflow_result.transitions[].user_description` | `string` | The user description of the state. |
| `workflow_result.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `workflow_result.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `workflow_result.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `workflow_result.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `workflow_result.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `workflow_result.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `workflow_result.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `workflow_result.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_result.graphical_layout_data` | `string` | Layout data of the workflow. |

---

# IRPCWorkflowsAdmin.GetWorkflows

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/

Badges: `Administration API / specialized` `admin` `session`

Gets the full administrative definitions of all workflows.

- **Service:** [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md) `MFiles.IRPCWorkflowsAdmin`
- **gRPC method:** `/MFiles.IRPCWorkflowsAdmin/GetWorkflows`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-workflows`
- **Request:** [`GetWorkflowsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/index.md#request)
- **Response:** [`GetWorkflowsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `read_all_metadata_structure`; a normal user gets "Access denied.".
- Returned 4 workflows in the Sample Vault. The order is undefined.

<a id="request"></a>

## Request: GetWorkflowsRequest

No fields.

<a id="response"></a>

## Response: GetWorkflowsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `workflow_results[]` | repeated [`WorkflowAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) | One [WorkflowAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) per workflow. |
| `workflow_results[].workflow` | [`Workflow`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Workflow/index.md) | Basic information on the workflow. |
| `workflow_results[].workflow.id` | `int32` | Workflow ID. |
| `workflow_results[].workflow.name` | `string` | The name of the workflow. |
| `workflow_results[].workflow.object_class_id` | `int32` | The class this workflow can be used with. |
| `workflow_results[].workflow.description` | `string` | The user description of the workflow. |
| `workflow_results[].workflow.reserved1_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow_results[].workflow.reserved2_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow_results[].description` | `string` | The description of the workflow. |
| `workflow_results[].states[]` | repeated [`State`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.State/index.md) | The states of this workflow. |
| `workflow_results[].states[].id` | `int32` | State ID. |
| `workflow_results[].states[].name` | `string` | The name of the state. |
| `workflow_results[].states[].description` | `string` | The description of the state. |
| `workflow_results[].states[].options` | [`ACTIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACTIONFLAGS/index.md) | Flags that tell which actions are enabled for this state. |
| `workflow_results[].states[].action_set_acl` | [`ActionSetACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetACL/index.md) | The properties of the Set Permissions action. |
| `workflow_results[].states[].action_assign_to_user` | [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | The properties of the Assign to User action. |
| `workflow_results[].states[].actions[]` | repeated [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | Action array. |
| `workflow_results[].states[].action_send_notification` | [`ActionSendNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSendNotification/index.md) | The properties of the Send Notification action. |
| `workflow_results[].states[].action_set_properties` | [`ActionSetProperties`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetProperties/index.md) | Action: set properties. |
| `workflow_results[].states[].action_convert_to_pdf` | [`ActionConvertToPDF`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionConvertToPDF/index.md) | Action: convert to PDF. |
| `workflow_results[].states[].action_code` | `string` | Action: run VBScript code. |
| `workflow_results[].states[].restrict_transitions` | `bool` | True if transitions involving this state must be individually allowed. |
| `workflow_results[].states[].transitions_require_edit_access_to_object` | `bool` | True if state transitions require edit access to the object. |
| `workflow_results[].states[].check_in_out_acl` | `bool` | True if the in/out permissions of this state should be checked. |
| `workflow_results[].states[].in_out_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The in/out permissions of this state. |
| `workflow_results[].states[].preconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State preconditions. (rules) |
| `workflow_results[].states[].postconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State postconditions. (rules) |
| `workflow_results[].states[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_results[].states[].user_description` | `string` | The user description of the state. |
| `workflow_results[].states[].state_flags` | [`STATEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.STATEFLAGS/index.md) | Flags that tell different options set for this state. |
| `workflow_results[].states[].agent_action_guid` | `string` | The agent action GUID of the state, or GUID_NULL if not set. |
| `workflow_results[].transitions[]` | repeated [`StateTransition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransition/index.md) | The state transitions of this workflow. |
| `workflow_results[].transitions[].id` | `int32` | State transition ID. |
| `workflow_results[].transitions[].from_state` | `int32` | The source state. |
| `workflow_results[].transitions[].to_state` | `int32` | The target state. |
| `workflow_results[].transitions[].evaluation_order` | `int32` | The evaluation order. |
| `workflow_results[].transitions[].name` | `string` | The name of the state. |
| `workflow_results[].transitions[].description` | `string` | The description of the state. |
| `workflow_results[].transitions[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Transition permissions. |
| `workflow_results[].transitions[].signature_settings` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | Signature settings for this state transition. |
| `workflow_results[].transitions[].trigger_mode` | [`AutoStateTransitionMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutoStateTransitionMode/index.md) | The selected mode for automatically triggered state transition. Values: `AUTO_STATE_TRANSITION_MODE_NONE` (0), `AUTO_STATE_TRANSITION_MODE_RELATIVE_TIME` (1), `AUTO_STATE_TRANSITION_MODE_CRITERIA_FULFILLED` (4), `AUTO_STATE_TRANSITION_MODE_SCRIPT_FULFILLED` (5), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_COMPLETE` (6), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_REJECTED` (7). |
| `workflow_results[].transitions[].trigger_in_days` | `uint32` | The number of days before automatically triggered state transition. |
| `workflow_results[].transitions[].trigger_criteria[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The criteria for automatically triggered state transition. |
| `workflow_results[].transitions[].trigger_code` | `string` | The VB script for automatically triggered state transition. |
| `workflow_results[].transitions[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_results[].transitions[].vault_guids[]` | repeated `string` | An array of GUIDS of vaults where this state transition will be triggered. |
| `workflow_results[].transitions[].user_description` | `string` | The user description of the state. |
| `workflow_results[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `workflow_results[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `workflow_results[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `workflow_results[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `workflow_results[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `workflow_results[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `workflow_results[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `workflow_results[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_results[].graphical_layout_data` | `string` | Layout data of the workflow. |

---

# IRPCWorkflowsAdmin.ModifyWorkflow

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/ModifyWorkflow/

Badges: `Administration API / specialized` `admin` `session`

Saves a changed workflow with its states and transitions.

- **Service:** [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md) `MFiles.IRPCWorkflowsAdmin`
- **gRPC method:** `/MFiles.IRPCWorkflowsAdmin/ModifyWorkflow`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-workflow`
- **Request:** [`ModifyWorkflowRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/ModifyWorkflow/index.md#request)
- **Response:** [`ModifyWorkflowResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/ModifyWorkflow/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Same rights, code rules and language rule as
  [AddWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/index.md).
- Send the complete workflow: start from
  [GetWorkflows](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/index.md). Existing states and transitions
  keep their IDs; new ones use negative placeholder IDs.
- Increments the metadata structure version.

<a id="request"></a>

## Request: ModifyWorkflowRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `workflow` | [`WorkflowAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) | The complete new workflow; `workflow.workflow.id` identifies it. |
| `workflow.workflow` | [`Workflow`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Workflow/index.md) | Basic information on the workflow. |
| `workflow.workflow.id` | `int32` | Workflow ID. |
| `workflow.workflow.name` | `string` | The name of the workflow. |
| `workflow.workflow.object_class_id` | `int32` | The class this workflow can be used with. |
| `workflow.workflow.description` | `string` | The user description of the workflow. |
| `workflow.workflow.reserved1_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow.workflow.reserved2_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow.description` | `string` | The description of the workflow. |
| `workflow.states[]` | repeated [`State`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.State/index.md) | The states of this workflow. |
| `workflow.states[].id` | `int32` | State ID. |
| `workflow.states[].name` | `string` | The name of the state. |
| `workflow.states[].description` | `string` | The description of the state. |
| `workflow.states[].options` | [`ACTIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACTIONFLAGS/index.md) | Flags that tell which actions are enabled for this state. |
| `workflow.states[].action_set_acl` | [`ActionSetACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetACL/index.md) | The properties of the Set Permissions action. |
| `workflow.states[].action_assign_to_user` | [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | The properties of the Assign to User action. |
| `workflow.states[].actions[]` | repeated [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | Action array. |
| `workflow.states[].action_send_notification` | [`ActionSendNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSendNotification/index.md) | The properties of the Send Notification action. |
| `workflow.states[].action_set_properties` | [`ActionSetProperties`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetProperties/index.md) | Action: set properties. |
| `workflow.states[].action_convert_to_pdf` | [`ActionConvertToPDF`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionConvertToPDF/index.md) | Action: convert to PDF. |
| `workflow.states[].action_code` | `string` | Action: run VBScript code. |
| `workflow.states[].restrict_transitions` | `bool` | True if transitions involving this state must be individually allowed. |
| `workflow.states[].transitions_require_edit_access_to_object` | `bool` | True if state transitions require edit access to the object. |
| `workflow.states[].check_in_out_acl` | `bool` | True if the in/out permissions of this state should be checked. |
| `workflow.states[].in_out_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The in/out permissions of this state. |
| `workflow.states[].preconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State preconditions. (rules) |
| `workflow.states[].postconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State postconditions. (rules) |
| `workflow.states[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow.states[].user_description` | `string` | The user description of the state. |
| `workflow.states[].state_flags` | [`STATEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.STATEFLAGS/index.md) | Flags that tell different options set for this state. |
| `workflow.states[].agent_action_guid` | `string` | The agent action GUID of the state, or GUID_NULL if not set. |
| `workflow.transitions[]` | repeated [`StateTransition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransition/index.md) | The state transitions of this workflow. |
| `workflow.transitions[].id` | `int32` | State transition ID. |
| `workflow.transitions[].from_state` | `int32` | The source state. |
| `workflow.transitions[].to_state` | `int32` | The target state. |
| `workflow.transitions[].evaluation_order` | `int32` | The evaluation order. |
| `workflow.transitions[].name` | `string` | The name of the state. |
| `workflow.transitions[].description` | `string` | The description of the state. |
| `workflow.transitions[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Transition permissions. |
| `workflow.transitions[].signature_settings` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | Signature settings for this state transition. |
| `workflow.transitions[].trigger_mode` | [`AutoStateTransitionMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutoStateTransitionMode/index.md) | The selected mode for automatically triggered state transition. Values: `AUTO_STATE_TRANSITION_MODE_NONE` (0), `AUTO_STATE_TRANSITION_MODE_RELATIVE_TIME` (1), `AUTO_STATE_TRANSITION_MODE_CRITERIA_FULFILLED` (4), `AUTO_STATE_TRANSITION_MODE_SCRIPT_FULFILLED` (5), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_COMPLETE` (6), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_REJECTED` (7). |
| `workflow.transitions[].trigger_in_days` | `uint32` | The number of days before automatically triggered state transition. |
| `workflow.transitions[].trigger_criteria[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The criteria for automatically triggered state transition. |
| `workflow.transitions[].trigger_code` | `string` | The VB script for automatically triggered state transition. |
| `workflow.transitions[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow.transitions[].vault_guids[]` | repeated `string` | An array of GUIDS of vaults where this state transition will be triggered. |
| `workflow.transitions[].user_description` | `string` | The user description of the state. |
| `workflow.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `workflow.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `workflow.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `workflow.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `workflow.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `workflow.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `workflow.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `workflow.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow.graphical_layout_data` | `string` | Layout data of the workflow. |

<a id="response"></a>

## Response: ModifyWorkflowResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `workflow_result` | [`WorkflowAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) | The workflow as stored, with real IDs for new states and transitions. |
| `workflow_result.workflow` | [`Workflow`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Workflow/index.md) | Basic information on the workflow. |
| `workflow_result.workflow.id` | `int32` | Workflow ID. |
| `workflow_result.workflow.name` | `string` | The name of the workflow. |
| `workflow_result.workflow.object_class_id` | `int32` | The class this workflow can be used with. |
| `workflow_result.workflow.description` | `string` | The user description of the workflow. |
| `workflow_result.workflow.reserved1_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow_result.workflow.reserved2_obsolete` | `uint32` | Reserved, must be zero. |
| `workflow_result.description` | `string` | The description of the workflow. |
| `workflow_result.states[]` | repeated [`State`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.State/index.md) | The states of this workflow. |
| `workflow_result.states[].id` | `int32` | State ID. |
| `workflow_result.states[].name` | `string` | The name of the state. |
| `workflow_result.states[].description` | `string` | The description of the state. |
| `workflow_result.states[].options` | [`ACTIONFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACTIONFLAGS/index.md) | Flags that tell which actions are enabled for this state. |
| `workflow_result.states[].action_set_acl` | [`ActionSetACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetACL/index.md) | The properties of the Set Permissions action. |
| `workflow_result.states[].action_assign_to_user` | [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | The properties of the Assign to User action. |
| `workflow_result.states[].actions[]` | repeated [`ActionSetAssignment`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetAssignment/index.md) | Action array. |
| `workflow_result.states[].action_send_notification` | [`ActionSendNotification`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSendNotification/index.md) | The properties of the Send Notification action. |
| `workflow_result.states[].action_set_properties` | [`ActionSetProperties`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionSetProperties/index.md) | Action: set properties. |
| `workflow_result.states[].action_convert_to_pdf` | [`ActionConvertToPDF`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ActionConvertToPDF/index.md) | Action: convert to PDF. |
| `workflow_result.states[].action_code` | `string` | Action: run VBScript code. |
| `workflow_result.states[].restrict_transitions` | `bool` | True if transitions involving this state must be individually allowed. |
| `workflow_result.states[].transitions_require_edit_access_to_object` | `bool` | True if state transitions require edit access to the object. |
| `workflow_result.states[].check_in_out_acl` | `bool` | True if the in/out permissions of this state should be checked. |
| `workflow_result.states[].in_out_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The in/out permissions of this state. |
| `workflow_result.states[].preconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State preconditions. (rules) |
| `workflow_result.states[].postconditions` | [`StateConditions`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateConditions/index.md) | State postconditions. (rules) |
| `workflow_result.states[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_result.states[].user_description` | `string` | The user description of the state. |
| `workflow_result.states[].state_flags` | [`STATEFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.STATEFLAGS/index.md) | Flags that tell different options set for this state. |
| `workflow_result.states[].agent_action_guid` | `string` | The agent action GUID of the state, or GUID_NULL if not set. |
| `workflow_result.transitions[]` | repeated [`StateTransition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransition/index.md) | The state transitions of this workflow. |
| `workflow_result.transitions[].id` | `int32` | State transition ID. |
| `workflow_result.transitions[].from_state` | `int32` | The source state. |
| `workflow_result.transitions[].to_state` | `int32` | The target state. |
| `workflow_result.transitions[].evaluation_order` | `int32` | The evaluation order. |
| `workflow_result.transitions[].name` | `string` | The name of the state. |
| `workflow_result.transitions[].description` | `string` | The description of the state. |
| `workflow_result.transitions[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Transition permissions. |
| `workflow_result.transitions[].signature_settings` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | Signature settings for this state transition. |
| `workflow_result.transitions[].trigger_mode` | [`AutoStateTransitionMode`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.AutoStateTransitionMode/index.md) | The selected mode for automatically triggered state transition. Values: `AUTO_STATE_TRANSITION_MODE_NONE` (0), `AUTO_STATE_TRANSITION_MODE_RELATIVE_TIME` (1), `AUTO_STATE_TRANSITION_MODE_CRITERIA_FULFILLED` (4), `AUTO_STATE_TRANSITION_MODE_SCRIPT_FULFILLED` (5), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_COMPLETE` (6), `AUTO_STATE_TRANSITION_MODE_ASSIGNMENT_REJECTED` (7). |
| `workflow_result.transitions[].trigger_in_days` | `uint32` | The number of days before automatically triggered state transition. |
| `workflow_result.transitions[].trigger_criteria[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The criteria for automatically triggered state transition. |
| `workflow_result.transitions[].trigger_code` | `string` | The VB script for automatically triggered state transition. |
| `workflow_result.transitions[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_result.transitions[].vault_guids[]` | repeated `string` | An array of GUIDS of vaults where this state transition will be triggered. |
| `workflow_result.transitions[].user_description` | `string` | The user description of the state. |
| `workflow_result.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `workflow_result.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `workflow_result.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `workflow_result.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `workflow_result.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `workflow_result.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `workflow_result.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `workflow_result.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `workflow_result.graphical_layout_data` | `string` | Layout data of the workflow. |

<a id="related"></a>

## Related methods

- [AddWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/AddWorkflow/index.md): Creates a workflow with its states and transitions.
- [GetWorkflows](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/GetWorkflows/index.md): Gets the full administrative definitions of all workflows.

---

# IRPCWorkflowsAdmin.RemoveWorkflow

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow/

Badges: `Administration API / specialized` `admin` `session`

Deletes a workflow with its states and transitions.

- **Service:** [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md) `MFiles.IRPCWorkflowsAdmin`
- **gRPC method:** `/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-workflow`
- **Request:** [`RemoveWorkflowRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow/index.md#request)
- **Response:** [`RemoveWorkflowResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `manage_workflows` and `license_allows_modifications`.
- Classes that used the workflow as their workflow no longer refer to it.
- An unknown ID fails with "Not found.". Increments the metadata structure version.

<a id="request"></a>

## Request: RemoveWorkflowRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the workflow to remove. |

<a id="response"></a>

## Response: RemoveWorkflowResponse

No fields.

---

# IRPCWorkflowsAdmin.RemoveWorkflows

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflows/

Badges: `Administration API / specialized` `admin` `session`

Deletes several workflows in one transaction.

- **Service:** [Workflow administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/index.md) `MFiles.IRPCWorkflowsAdmin`
- **gRPC method:** `/MFiles.IRPCWorkflowsAdmin/RemoveWorkflows`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-workflows`
- **Request:** [`RemoveWorkflowsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflows/index.md#request)
- **Response:** [`RemoveWorkflowsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflows/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Same rules as [RemoveWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow/index.md); if one
  workflow cannot be removed, none are.

<a id="request"></a>

## Request: RemoveWorkflowsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `workflow_ids[]` | repeated `int32` | The IDs of workflows to delete. |

<a id="response"></a>

## Response: RemoveWorkflowsResponse

No fields.

<a id="related"></a>

## Related methods

- [RemoveWorkflow](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWorkflowsAdmin/RemoveWorkflow/index.md): Deletes a workflow with its states and transitions.

---

# Common views administration (IRPCViewsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/

Reads the common views and every user's private views of a vault, for administrators.

Use this interface to get views.

- **gRPC service:** `MFiles.IRPCViewsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 1
- **Proto file:** [`mfiles/IRPCViewsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCViewsAdmin.proto)

<a id="overview"></a>

## Overview

The service has one method,
[GetViewsAndUsersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/GetViewsAndUsersAdmin/index.md). M-Files Admin uses
it when it exports the structure of a vault, to list the views it can include. To read and
manage the caller's own views and the common views, use [IRPCViews](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViews/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [GetViewsAndUsersAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/GetViewsAndUsersAdmin/index.md) | Gets all common views and the private views of all users, with the owner of each private view. | `admin` `session` `idempotent` |

---

# IRPCViewsAdmin.GetViewsAndUsersAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Common views administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/GetViewsAndUsersAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all common views and the private views of all users, with the owner of each private view.

- **Service:** [Common views administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/index.md) `MFiles.IRPCViewsAdmin`
- **gRPC method:** `/MFiles.IRPCViewsAdmin/GetViewsAndUsersAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-views-and-users-admin`
- **Request:** [`GetViewsAndUsersAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/GetViewsAndUsersAdmin/index.md#request)
- **Response:** [`GetViewsAndUsersAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCViewsAdmin/GetViewsAndUsersAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with the vault rights `manage_users` and `archive`
  ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)). The caller does not need a user account in the
  vault.
- `user_defined_views` and `user_accounts` are parallel lists: `user_accounts[i]` owns
  `user_defined_views[i]`, so an owner with several views appears several times. They are
  ordered by user ID. Views of the anonymous user are left out.
- The owner entries contain the ID, login name, vault roles, permissions and language of the
  user; `external_id` is not filled.
- The order of the common views is not specified. Names are in the session language.

<a id="request"></a>

## Request: GetViewsAndUsersAdminRequest

No fields.

<a id="response"></a>

## Response: GetViewsAndUsersAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `user_defined_views[]` | repeated [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | The private views of all users. See [View](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md). |
| `user_defined_views[].id` | `int32` | The ID of the view. |
| `user_defined_views[].type` | [`ViewType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ViewType/index.md) | The type of the view. Values: `VIEW_TYPE_SHOW_OBJECTS` (0), `VIEW_TYPE_FILTER_ONLY` (1). |
| `user_defined_views[].name` | `string` | The name of the view. |
| `user_defined_views[].is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `user_defined_views[].is_visible` | `bool` | Tells if the view is visible. |
| `user_defined_views[].location` | [`ViewLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewLocation/index.md) | The location of the view. Valid only if bHasParent is true. |
| `user_defined_views[].location.parent_folder[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Array of folders describing the parent folder of the view. The first element of the array must be a view folder. Other elements, if any, are property folders. |
| `user_defined_views[].location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `user_defined_views[].location.customized_property_folder` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The overlapped property folder. Ignored if bOverlapping is false. |
| `user_defined_views[].content_definition` | [`SearchDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchDef/index.md) | The search definition that contains the view levels and search conditions of the view. |
| `user_defined_views[].content_definition.filter_conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions that limit the object set of this search. |
| `user_defined_views[].content_definition.grouping_levels[]` | repeated [`GroupingLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.GroupingLevel/index.md) | View levels (the display hierarchy of this search). |
| `user_defined_views[].content_definition.options` | [`SearchFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md) | Search flags. This affects the resulting object version set and also distinct view level values displayed inside this search. |
| `user_defined_views[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `user_defined_views[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `user_defined_views[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `user_defined_views[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `user_defined_views[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `user_defined_views[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `user_defined_views[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `user_defined_views[].flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `user_defined_views[].options` | [`VIEWFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VIEWFLAGS/index.md) | Bit flags that provide additional information on the view. |
| `user_defined_views[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `user_defined_views[].options.indexed` | `bool` | Materialized/indexed view. |
| `user_defined_views[].options.incompatible_with_full_text_search` | `bool` | The search conditions of the view definition (excluding the grouping levels) are not compatible with full-text search. |
| `user_defined_views[].options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `user_defined_views[].guid` | `string` | GUID for the view. |
| `user_defined_views[].view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `user_defined_views[].view_visualization.subview_groups[]` | repeated [`SubviewGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SubviewGroup/index.md) | The subviews of the view as groups. |
| `user_accounts[]` | repeated [`UserAccount`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccount/index.md) | The owner of each private view, in the order of `user_defined_views`. |
| `user_accounts[].id` | `int32` | The ID of the user account. |
| `user_accounts[].login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `user_accounts[].vault_roles` | [`VAULTROLES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VAULTROLES/index.md) | Bitmask of the vault roles of the user. |
| `user_accounts[].vault_roles.all` | `bool` | Specifies all flags set; Including any future flags. |
| `user_accounts[].vault_roles.full_control` | `bool` | Can perform any activity in the vault. |
| `user_accounts[].vault_roles.can_log_in` | `bool` | Can log in to the vault. |
| `user_accounts[].vault_roles.can_create_objects` | `bool` | Can create new documents. |
| `user_accounts[].vault_roles.can_see_all_objects` | `bool` | Sees all documents in listings, regardless of security settings and deletion state. |
| `user_accounts[].vault_roles.can_undelete_objects` | `bool` | Can undelete previously deleted documents. |
| `user_accounts[].vault_roles.can_destroy_objects` | `bool` | Has permission to permanently destroy documents. |
| `user_accounts[].vault_roles.can_force_undo_checkout` | `bool` | Has permission to undo a check-out performed by another user. |
| `user_accounts[].vault_roles.can_change_all_object_permissions` | `bool` | Can change the security settings of all documents and modify all documents. |
| `user_accounts[].vault_roles.can_change_metadata_structure` | `bool` | Can modify the meta data structure of the vault (propertydefs, profiles, value lists etc.). |
| `user_accounts[].vault_roles.can_manage_users` | `bool` | Can create, edit and delete user accounts. Cannot add or remove the Vault Manager role. |
| `user_accounts[].vault_roles.is_internal_user` | `bool` | An internal user of the vault. This role separates internal enad external users in the vault. |
| `user_accounts[].vault_roles.can_manage_traditional_folders` | `bool` | Can create, modify and delete traditional folders. OBSOLETE: const VAULTROLES VAULTROLE_DEFINE_TEMPLATES = 1 << 12;  //!< Can define templates. |
| `user_accounts[].vault_roles.can_manage_common_views` | `bool` | Can create, modify and delete common views. |
| `user_accounts[].vault_roles.can_manage_workflows` | `bool` | Can create, modify and delete workflows. Modifying event handlers within the workflow still requires SERVERACCESS_RUN_CODE. |
| `user_accounts[].vault_roles.cannot_manage_private_views` | `bool` | Cannot create or modify private views. |
| `user_accounts[].vault_roles.anonymous` | `bool` | Anonymous role. |
| `user_accounts[].vault_roles.run_code_on_server` | `bool` | Can run code on the server hosting this vault. Not included in VAULTROLE_FULL_CONTROL, and cannot be ordinarily granted by it. |
| `user_accounts[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `user_accounts[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `user_accounts[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `user_accounts[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `user_accounts[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `user_accounts[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `user_accounts[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `user_accounts[].user_language` | `int32` | The vault language of the user. |
| `user_accounts[].external_id` | `string` | The user identity in external system, such as Microsoft Entra (where the identity is a GUID). Read-only. |
| `u_common_views[]` | repeated [`View`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.View/index.md) | All common views. |
| `u_common_views[].id` | `int32` | The ID of the view. |
| `u_common_views[].type` | [`ViewType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ViewType/index.md) | The type of the view. Values: `VIEW_TYPE_SHOW_OBJECTS` (0), `VIEW_TYPE_FILTER_ONLY` (1). |
| `u_common_views[].name` | `string` | The name of the view. |
| `u_common_views[].is_common` | `bool` | Tells if the view is admin-defined (common) or user-defined. |
| `u_common_views[].is_visible` | `bool` | Tells if the view is visible. |
| `u_common_views[].location` | [`ViewLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewLocation/index.md) | The location of the view. Valid only if bHasParent is true. |
| `u_common_views[].location.parent_folder[]` | repeated [`Folder`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Folder/index.md) | Array of folders describing the parent folder of the view. The first element of the array must be a view folder. Other elements, if any, are property folders. |
| `u_common_views[].location.customizes_property_folder` | `bool` | True if the view is overlapping with a property folder. |
| `u_common_views[].location.customized_property_folder` | [`TypedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TypedValue/index.md) | The overlapped property folder. Ignored if bOverlapping is false. |
| `u_common_views[].content_definition` | [`SearchDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchDef/index.md) | The search definition that contains the view levels and search conditions of the view. |
| `u_common_views[].content_definition.filter_conditions[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions that limit the object set of this search. |
| `u_common_views[].content_definition.grouping_levels[]` | repeated [`GroupingLevel`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.GroupingLevel/index.md) | View levels (the display hierarchy of this search). |
| `u_common_views[].content_definition.options` | [`SearchFlags`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchFlags/index.md) | Search flags. This affects the resulting object version set and also distinct view level values displayed inside this search. |
| `u_common_views[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `u_common_views[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `u_common_views[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `u_common_views[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `u_common_views[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `u_common_views[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `u_common_views[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `u_common_views[].flags_obsolete` | `uint32` | Bit flags that provide additional information on the view. |
| `u_common_views[].options` | [`VIEWFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VIEWFLAGS/index.md) | Bit flags that provide additional information on the view. |
| `u_common_views[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `u_common_views[].options.indexed` | `bool` | Materialized/indexed view. |
| `u_common_views[].options.incompatible_with_full_text_search` | `bool` | The search conditions of the view definition (excluding the grouping levels) are not compatible with full-text search. |
| `u_common_views[].options.sort_across_all_pages_disabled` | `bool` | Sorting search results is disabled. |
| `u_common_views[].guid` | `string` | GUID for the view. |
| `u_common_views[].view_visualization` | [`ViewVisualization`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ViewVisualization/index.md) | View visualization information. |
| `u_common_views[].view_visualization.subview_groups[]` | repeated [`SubviewGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SubviewGroup/index.md) | The subviews of the view as groups. |

---

# Named access control list administration (IRPCNamedACLsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/

Adds, reads, modifies and removes the named access control lists (permission templates) of a
vault.

Use this interface to add, modify and delete named ACLs in a vault.

- **gRPC service:** `MFiles.IRPCNamedACLsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 5
- **Proto file:** [`mfiles/IRPCNamedACLsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCNamedACLsAdmin.proto)

<a id="overview"></a>

## Overview

A named ACL is a reusable set of permissions with a name, such as "Visible to company management
only". Users pick one when they set the permissions of an object; value list items and classes
can apply one automatically. See
[Permissions](https://developer.m-files.com/APIs/gRPC-API/concepts/permissions/index.md). M-Files Admin
uses this service for the Named access control lists node of a vault.

- **Session and rights.** Requires a vault session. Reading needs the vault right
  `read_all_metadata_structure` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); adding, modifying and
  removing need `change_metadata_structure` and `license_allows_modifications`.
- **Two ACLs per named ACL** ([NamedACLAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md)):
  `named_acl.acl_for_objects` is the permission set that objects get; `acl` controls who can see
  and select the named ACL.
- **Types.** `NACLTYPE_NORMAL` named ACLs are offered to users. `NACLTYPE_INTERNAL` named ACLs
  hold automatic permissions defined on value list items and classes, and are not offered to
  users.
- **Built-in named ACLs** have negative IDs, for example -1 "Full control for all internal
  users" and -20 "Only for me".
- Objects that use a named ACL stay linked to it: modifying the named ACL can update their
  permissions in the background, see
  [ModifyNamedACL](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/ModifyNamedACL/index.md).

Users who are not administrators read the named ACLs they can select with
[GetNamedACLs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddNamedACL](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/AddNamedACL/index.md) | Adds a named ACL to the vault. | `admin` `session` |
| [GetNamedACLsForAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/GetNamedACLsForAdmin/index.md) | Gets the named ACLs of the given types, including the ACLs that control who sees them. | `admin` `session` `idempotent` |
| [IsNamedACLUsedInAutomaticPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/IsNamedACLUsedInAutomaticPermissions/index.md) | Tells whether a named ACL is used in the automatic permissions of any value list item or class. | `admin` `session` `idempotent` |
| [ModifyNamedACL](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/ModifyNamedACL/index.md) | Changes a named ACL, and optionally the permissions of the objects that use it. | `admin` `session` `idempotent` |
| [RemoveNamedACL](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/RemoveNamedACL/index.md) | Removes a named ACL from the vault. | `admin` `session` |

---

# IRPCNamedACLsAdmin.AddNamedACL

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/AddNamedACL/

Badges: `Administration API / specialized` `admin` `session`

Adds a named ACL to the vault.

- **Service:** [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md) `MFiles.IRPCNamedACLsAdmin`
- **gRPC method:** `/MFiles.IRPCNamedACLsAdmin/AddNamedACL`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-named-acl`
- **Request:** [`AddNamedACLRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/AddNamedACL/index.md#request)
- **Response:** [`AddNamedACLResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/AddNamedACL/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `change_metadata_structure` and `license_allows_modifications`.
- The name must be unique (compared case-insensitively).
- The server assigns the ID and the GUID; the values you send are ignored.

<a id="request"></a>

## Request: AddNamedACLRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `named_acladmin` | [`NamedACLAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md) | The new named ACL. See [NamedACLAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md). |
| `named_acladmin.named_acl` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | Basic data. |
| `named_acladmin.named_acl.id` | `int32` | Named ACL ID. |
| `named_acladmin.named_acl.name` | `string` | The name of the named ACL. |
| `named_acladmin.named_acl.type` | [`NACLType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) | The type of the NACL. Values: `NACLTYPE_NONE` (0), `NACLTYPE_NORMAL` (1), `NACLTYPE_INTERNAL` (2). |
| `named_acladmin.named_acl.acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The predefined permissions. This defines the ACL which this named ACL encapsulates. |
| `named_acladmin.named_acl.guid` | `string` | GUID for the NACL. |
| `named_acladmin.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of this named ACL. This defines which users can see this named ACL, for example. |
| `named_acladmin.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `named_acladmin.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `named_acladmin.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `named_acladmin.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `named_acladmin.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `named_acladmin.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `named_acladmin.aliases` | `string` | Semicolon-separated list of semantic aliases. |

<a id="response"></a>

## Response: AddNamedACLResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `putf8sznamedacladmin` | [`NamedACLAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md) | The stored named ACL with its new ID and GUID. |
| `putf8sznamedacladmin.named_acl` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | Basic data. |
| `putf8sznamedacladmin.named_acl.id` | `int32` | Named ACL ID. |
| `putf8sznamedacladmin.named_acl.name` | `string` | The name of the named ACL. |
| `putf8sznamedacladmin.named_acl.type` | [`NACLType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) | The type of the NACL. Values: `NACLTYPE_NONE` (0), `NACLTYPE_NORMAL` (1), `NACLTYPE_INTERNAL` (2). |
| `putf8sznamedacladmin.named_acl.acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The predefined permissions. This defines the ACL which this named ACL encapsulates. |
| `putf8sznamedacladmin.named_acl.guid` | `string` | GUID for the NACL. |
| `putf8sznamedacladmin.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of this named ACL. This defines which users can see this named ACL, for example. |
| `putf8sznamedacladmin.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `putf8sznamedacladmin.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `putf8sznamedacladmin.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `putf8sznamedacladmin.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `putf8sznamedacladmin.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `putf8sznamedacladmin.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `putf8sznamedacladmin.aliases` | `string` | Semicolon-separated list of semantic aliases. |

---

# IRPCNamedACLsAdmin.GetNamedACLsForAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/GetNamedACLsForAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the named ACLs of the given types, including the ACLs that control who sees them.

- **Service:** [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md) `MFiles.IRPCNamedACLsAdmin`
- **gRPC method:** `/MFiles.IRPCNamedACLsAdmin/GetNamedACLsForAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-named-acls-for-admin`
- **Request:** [`GetNamedACLsForAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/GetNamedACLsForAdmin/index.md#request)
- **Response:** [`GetNamedACLsForAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/GetNamedACLsForAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault right `read_all_metadata_structure`.
- Built-in named ACLs (negative IDs) are included. "Current user" entries are returned as such;
  they are not replaced with the caller's identity as in
  [GetNamedACLs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md).
- `nacl_types` 0 returns an empty list. Names are in the session language. The order is not
  specified.

<a id="request"></a>

## Request: GetNamedACLsForAdminRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `nacl_types` | `uint32` | Which types to return, as a bit mask of [NACLType](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) values: 1 normal, 2 internal, 3 both. |

<a id="response"></a>

## Response: GetNamedACLsForAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`NamedACLAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md) | The named ACLs. See [NamedACLAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md). |
| `values[].named_acl` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | Basic data. |
| `values[].named_acl.id` | `int32` | Named ACL ID. |
| `values[].named_acl.name` | `string` | The name of the named ACL. |
| `values[].named_acl.type` | [`NACLType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) | The type of the NACL. Values: `NACLTYPE_NONE` (0), `NACLTYPE_NORMAL` (1), `NACLTYPE_INTERNAL` (2). |
| `values[].named_acl.acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The predefined permissions. This defines the ACL which this named ACL encapsulates. |
| `values[].named_acl.guid` | `string` | GUID for the NACL. |
| `values[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of this named ACL. This defines which users can see this named ACL, for example. |
| `values[].acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `values[].acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `values[].acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `values[].acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `values[].acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `values[].acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `values[].aliases` | `string` | Semicolon-separated list of semantic aliases. |

<a id="related"></a>

## Related methods

- [IRPCNamedACLs.GetNamedACLs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLs/GetNamedACLs/index.md): Gets the named ACLs of the given types that the calling user is allowed to see.

---

# IRPCNamedACLsAdmin.IsNamedACLUsedInAutomaticPermissions

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/IsNamedACLUsedInAutomaticPermissions/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Tells whether a named ACL is used in the automatic permissions of any value list item or class.

- **Service:** [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md) `MFiles.IRPCNamedACLsAdmin`
- **gRPC method:** `/MFiles.IRPCNamedACLsAdmin/IsNamedACLUsedInAutomaticPermissions`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/is-named-aclused-in-automatic-permissions`
- **Request:** [`IsNamedACLUsedInAutomaticPermissionsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/IsNamedACLUsedInAutomaticPermissions/index.md#request)
- **Response:** [`IsNamedACLUsedInAutomaticPermissionsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/IsNamedACLUsedInAutomaticPermissions/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session; no vault rights are needed.
- A named ACL that is used in automatic permissions cannot be removed with
  [RemoveNamedACL](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/RemoveNamedACL/index.md). An unknown ID returns
  false.

<a id="request"></a>

## Request: IsNamedACLUsedInAutomaticPermissionsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the named ACL, or -2147483648 to ask whether any named ACL is used. |

<a id="response"></a>

## Response: IsNamedACLUsedInAutomaticPermissionsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `used_in_automatic_permissions` | `bool` | True if the named ACL is used in automatic permissions. |

<a id="related"></a>

## Related methods

- [RemoveNamedACL](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/RemoveNamedACL/index.md): Removes a named ACL from the vault.

---

# IRPCNamedACLsAdmin.ModifyNamedACL

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/ModifyNamedACL/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Changes a named ACL, and optionally the permissions of the objects that use it.

- **Service:** [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md) `MFiles.IRPCNamedACLsAdmin`
- **gRPC method:** `/MFiles.IRPCNamedACLsAdmin/ModifyNamedACL`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-named-acl`
- **Request:** [`ModifyNamedACLRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/ModifyNamedACL/index.md#request)
- **Response:** [`ModifyNamedACLResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/ModifyNamedACL/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `change_metadata_structure` and `license_allows_modifications`.
- When objects must get new permissions, the server starts a background task and returns before
  it completes; `task_idchange_objects` identifies it.
- The type cannot be changed, and the name must stay unique. A named ACL used in automatic
  permissions cannot contain a "current user" entry.
- Send the complete named ACL: read it with
  [GetNamedACLsForAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/GetNamedACLsForAdmin/index.md) first.

<a id="request"></a>

## Request: ModifyNamedACLRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `named_acladmin` | [`NamedACLAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md) | The complete new data; `named_acl.id` identifies the named ACL. |
| `named_acladmin.named_acl` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | Basic data. |
| `named_acladmin.named_acl.id` | `int32` | Named ACL ID. |
| `named_acladmin.named_acl.name` | `string` | The name of the named ACL. |
| `named_acladmin.named_acl.type` | [`NACLType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) | The type of the NACL. Values: `NACLTYPE_NONE` (0), `NACLTYPE_NORMAL` (1), `NACLTYPE_INTERNAL` (2). |
| `named_acladmin.named_acl.acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The predefined permissions. This defines the ACL which this named ACL encapsulates. |
| `named_acladmin.named_acl.guid` | `string` | GUID for the NACL. |
| `named_acladmin.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of this named ACL. This defines which users can see this named ACL, for example. |
| `named_acladmin.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `named_acladmin.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `named_acladmin.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `named_acladmin.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `named_acladmin.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `named_acladmin.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `named_acladmin.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `maintain_links` | `bool` | True to apply the change to the objects that use the named ACL. False to leave their permissions as they are and remove their link to the named ACL. |
| `allow_propagation` | `bool` | True to allow the change to reach the objects as `maintain_links` says. False to fail the call instead if any object would be affected. |

<a id="response"></a>

## Response: ModifyNamedACLResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `putf8sznamedacladmin` | [`NamedACLAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md) | The stored named ACL. |
| `putf8sznamedacladmin.named_acl` | [`NamedACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACL/index.md) | Basic data. |
| `putf8sznamedacladmin.named_acl.id` | `int32` | Named ACL ID. |
| `putf8sznamedacladmin.named_acl.name` | `string` | The name of the named ACL. |
| `putf8sznamedacladmin.named_acl.type` | [`NACLType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.NACLType/index.md) | The type of the NACL. Values: `NACLTYPE_NONE` (0), `NACLTYPE_NORMAL` (1), `NACLTYPE_INTERNAL` (2). |
| `putf8sznamedacladmin.named_acl.acl_for_objects` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The predefined permissions. This defines the ACL which this named ACL encapsulates. |
| `putf8sznamedacladmin.named_acl.guid` | `string` | GUID for the NACL. |
| `putf8sznamedacladmin.acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | The permissions of this named ACL. This defines which users can see this named ACL, for example. |
| `putf8sznamedacladmin.acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `putf8sznamedacladmin.acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `putf8sznamedacladmin.acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `putf8sznamedacladmin.acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `putf8sznamedacladmin.acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `putf8sznamedacladmin.acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `putf8sznamedacladmin.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `task_idchange_objects` | `int64` | The ID of the background task that updates the objects, or -1 if no objects needed changes. |

<a id="related"></a>

## Related methods

- [GetNamedACLsForAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/GetNamedACLsForAdmin/index.md): Gets the named ACLs of the given types, including the ACLs that control who sees them.

---

# IRPCNamedACLsAdmin.RemoveNamedACL

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/RemoveNamedACL/

Badges: `Administration API / specialized` `admin` `session`

Removes a named ACL from the vault.

- **Service:** [Named access control list administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/index.md) `MFiles.IRPCNamedACLsAdmin`
- **gRPC method:** `/MFiles.IRPCNamedACLsAdmin/RemoveNamedACL`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-named-acl`
- **Request:** [`RemoveNamedACLRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/RemoveNamedACL/index.md#request)
- **Response:** [`RemoveNamedACLResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/RemoveNamedACL/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Deletes the named ACL permanently. Objects keep their current permissions; with
  `allow_propagation` their link to the named ACL is removed in a background task.
- Requires the vault rights `change_metadata_structure` and `license_allows_modifications`.
- Fails if the named ACL is used in automatic permissions; check with
  [IsNamedACLUsedInAutomaticPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/IsNamedACLUsedInAutomaticPermissions/index.md).
- Changes the metadata structure version.

<a id="request"></a>

## Request: RemoveNamedACLRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the named ACL to remove. |
| `allow_propagation` | `bool` | True to remove the link from the objects that use the named ACL. False to fail the call instead if any object uses it. |

<a id="response"></a>

## Response: RemoveNamedACLResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `task_idchange_objects` | `int64` | The ID of the background task that updates the objects, or -1 if no objects needed changes. |

<a id="related"></a>

## Related methods

- [IsNamedACLUsedInAutomaticPermissions](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCNamedACLsAdmin/IsNamedACLUsedInAutomaticPermissions/index.md): Tells whether a named ACL is used in the automatic permissions of any value list item or class.

---

# Language administration (IRPCLanguagesAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/

Adds, modifies and removes the languages of a vault, and reads and writes the translations of
its metadata structure names.

Use this interface to add, modify and delete languages in a vault.

- **gRPC service:** `MFiles.IRPCLanguagesAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 5
- **Proto file:** [`mfiles/IRPCLanguagesAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCLanguagesAdmin.proto)

<a id="overview"></a>

## Overview

A vault has a default language (ID 0) and can have additional languages. The names of the
metadata structure (classes, property definitions, value lists, views, workflows, named ACLs,
...) can be translated to each language; users see the names in their session language. M-Files
Admin uses this service to manage the languages and translations of a vault.

- **Session and rights.** Requires a vault session with the vault rights
  `change_metadata_structure` and `license_allows_modifications`
  ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)). Reading and writing translations also needs
  `see_all_objects`.
- **License.** Adding and modifying languages and applying translations fail when the server's
  license does not include the languages feature.
- **List the languages** with [GetLanguages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguages/GetLanguages/index.md); this
  service has no read method for them.
- **Translate the vault:** [GetTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/GetTranslations/index.md)
  with the default language as source and the target language, fill in `target_string` and
  set `state` to `TRANSLATION_STATE_TRANSLATED`, then
  [ApplyTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ApplyTranslations/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddLanguage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/AddLanguage/index.md) | Adds a language to the vault. | `admin` `session` |
| [ApplyTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ApplyTranslations/index.md) | Stores translated names in a target language. | `admin` `session` `idempotent` |
| [GetTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/GetTranslations/index.md) | Gets the translatable names of the vault's metadata structure, with their texts in a source and a target language. | `admin` `session` `idempotent` |
| [ModifyLanguage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ModifyLanguage/index.md) | Changes the name or language code of a language. | `admin` `session` `idempotent` |
| [RemoveLanguage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/RemoveLanguage/index.md) | Removes an additional language from the vault. | `admin` `session` |

---

# IRPCLanguagesAdmin.AddLanguage

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/AddLanguage/

Badges: `Administration API / specialized` `admin` `session`

Adds a language to the vault.

- **Service:** [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md) `MFiles.IRPCLanguagesAdmin`
- **gRPC method:** `/MFiles.IRPCLanguagesAdmin/AddLanguage`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-language`
- **Request:** [`AddLanguageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/AddLanguage/index.md#request)
- **Response:** [`AddLanguageResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/AddLanguage/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `change_metadata_structure` and `license_allows_modifications`, and
  a server license that includes the languages feature.
- The server assigns the ID; the value you send is ignored.

<a id="request"></a>

## Request: AddLanguageRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `lang` | [`Language`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Language/index.md) | The new language: `name` and `language_code` (for example `fi`). `id` is ignored. |
| `lang.id` | `int32` | Language ID. |
| `lang.name` | `string` | The name of the language. |
| `lang.language_code` | `string` | Language indentifier, e.g. the ISO 639-1 or ISO 639-2 language code such as "en" or "eng". |

<a id="response"></a>

## Response: AddLanguageResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new language. |

---

# IRPCLanguagesAdmin.ApplyTranslations

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ApplyTranslations/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Stores translated names in a target language.

- **Service:** [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md) `MFiles.IRPCLanguagesAdmin`
- **gRPC method:** `/MFiles.IRPCLanguagesAdmin/ApplyTranslations`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/apply-translations`
- **Request:** [`ApplyTranslationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ApplyTranslations/index.md#request)
- **Response:** [`ApplyTranslationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ApplyTranslations/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `change_metadata_structure`, `license_allows_modifications` and
  `see_all_objects`, and a server license that includes the languages feature.
- When at least one translation is stored, the metadata structure version changes (clients reload the
  names) and the vault's search indexes are marked for re-indexing.

<a id="request"></a>

## Request: ApplyTranslationsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `target_language` | `int32` | The language the translations are for. |
| `ptranslations[]` | repeated [`Translation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Translation/index.md) | The translations, as returned by [GetTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/GetTranslations/index.md) with `target_string` and `state` filled in. |
| `ptranslations[].id` | `string` | Identifier. |
| `ptranslations[].source_string` | `string` | The source string, or unset or an empty string. |
| `ptranslations[].source_version` | `int32` | The version of the source string, or zero. |
| `ptranslations[].target_string` | `string` | The target string, or unset or an empty string. |
| `ptranslations[].state` | [`TranslationState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.TranslationState/index.md) | The state of the target string, or etsNotTranslated. Values: `TRANSLATION_STATE_NOT_TRANSLATED` (0), `TRANSLATION_STATE_TRANSLATED` (1). |
| `apply_translated_only` | `bool` | True to store only the entries whose `state` is `TRANSLATION_STATE_TRANSLATED`. |

<a id="response"></a>

## Response: ApplyTranslationsResponse

No fields.

---

# IRPCLanguagesAdmin.GetTranslations

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/GetTranslations/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the translatable names of the vault's metadata structure, with their texts in a source and
a target language.

- **Service:** [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md) `MFiles.IRPCLanguagesAdmin`
- **gRPC method:** `/MFiles.IRPCLanguagesAdmin/GetTranslations`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-translations`
- **Request:** [`GetTranslationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/GetTranslations/index.md#request)
- **Response:** [`GetTranslationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/GetTranslations/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `change_metadata_structure`, `license_allows_modifications` and
  `see_all_objects`.
- Returns one [Translation](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Translation/index.md) per name that exists in the default
  language, including the items of translatable value lists. `id` identifies the name, for
  example `PropertyDef_20_0_Name`; send it back unchanged in
  [ApplyTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ApplyTranslations/index.md).
- If neither `include_source_language` nor `include_target_language` is true, the list is
  empty.
- `untranslated_only` filters on the target language's state, so it returns nothing unless
  `include_target_language` is true.

<a id="request"></a>

## Request: GetTranslationsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `include_source_language` | `bool` | True to fill `source_string` and `source_version`. |
| `source_language` | `int32` | The language of `source_string`, usually 0 (the default language). Used only with `include_source_language`. |
| `include_target_language` | `bool` | True to fill `target_string` and `state`. |
| `target_language` | `int32` | The language being translated to. Used only with `include_target_language`. |
| `untranslated_only` | `bool` | True to return only names whose target text is not translated yet. Requires `include_target_language`. |

<a id="response"></a>

## Response: GetTranslationsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`Translation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Translation/index.md) | The translatable names. See [Translation](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Translation/index.md). |
| `values[].id` | `string` | Identifier. |
| `values[].source_string` | `string` | The source string, or unset or an empty string. |
| `values[].source_version` | `int32` | The version of the source string, or zero. |
| `values[].target_string` | `string` | The target string, or unset or an empty string. |
| `values[].state` | [`TranslationState`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.TranslationState/index.md) | The state of the target string, or etsNotTranslated. Values: `TRANSLATION_STATE_NOT_TRANSLATED` (0), `TRANSLATION_STATE_TRANSLATED` (1). |

<a id="related"></a>

## Related methods

- [ApplyTranslations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ApplyTranslations/index.md): Stores translated names in a target language.

---

# IRPCLanguagesAdmin.ModifyLanguage

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ModifyLanguage/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Changes the name or language code of a language.

- **Service:** [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md) `MFiles.IRPCLanguagesAdmin`
- **gRPC method:** `/MFiles.IRPCLanguagesAdmin/ModifyLanguage`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-language`
- **Request:** [`ModifyLanguageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ModifyLanguage/index.md#request)
- **Response:** [`ModifyLanguageResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/ModifyLanguage/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the vault rights `change_metadata_structure` and `license_allows_modifications`, and
  a server license that includes the languages feature.
- The default language (0) and additional languages can be modified; a negative ID fails with
  "Access denied".

<a id="request"></a>

## Request: ModifyLanguageRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `lang` | [`Language`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Language/index.md) | The new data of the language; `id` identifies the language. |
| `lang.id` | `int32` | Language ID. |
| `lang.name` | `string` | The name of the language. |
| `lang.language_code` | `string` | Language indentifier, e.g. the ISO 639-1 or ISO 639-2 language code such as "en" or "eng". |

<a id="response"></a>

## Response: ModifyLanguageResponse

No fields.

---

# IRPCLanguagesAdmin.RemoveLanguage

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/RemoveLanguage/

Badges: `Administration API / specialized` `admin` `session`

Removes an additional language from the vault.

- **Service:** [Language administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/index.md) `MFiles.IRPCLanguagesAdmin`
- **gRPC method:** `/MFiles.IRPCLanguagesAdmin/RemoveLanguage`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-language`
- **Request:** [`RemoveLanguageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/RemoveLanguage/index.md#request)
- **Response:** [`RemoveLanguageResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLanguagesAdmin/RemoveLanguage/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Deletes the language permanently. Requires the vault rights `change_metadata_structure` and
  `license_allows_modifications`.
- Only additional languages can be removed: ID 0 (the default language) or a negative ID fails
  with "Access denied".

<a id="request"></a>

## Request: RemoveLanguageRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the language to remove. |

<a id="response"></a>

## Response: RemoveLanguageResponse

No fields.

---

# Event handlers (IRPCEventHandlersAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/

Reads and replaces the event handlers of a vault or of the server: VBScript code that the server
runs when an event occurs.

MFAdmin uses this interface to admininistrate event handlers.

- **gRPC service:** `MFiles.IRPCEventHandlersAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 4
- **Proto file:** [`mfiles/IRPCEventHandlersAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCEventHandlersAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service for its event handler editor, and vault applications use it to
register their own handlers. An event handler is an
[InternalEventHandler](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.InternalEventHandler/index.md): the event it reacts to
(`event_type`), its position among the handlers of the same event (`sort_index`), `is_active`, a
`description`, and the `code` that the server runs.

- **Vault event handlers** run in one vault:
  [GetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers/index.md),
  [SetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers/index.md). They need
  a vault session.
- **Server event handlers** are stored once for the whole server:
  [GetServerEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetServerEventHandlers/index.md),
  [SetServerEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetServerEventHandlers/index.md). A
  server-level session is enough.

The `Set` methods replace the whole list: read it, change it, and write all handlers back. To
keep a handler, send it back with its `guid`; a handler left out is removed.

**Rights.** Handler code runs on the server, so writing it needs the right to run code there:

- Server right `run_code` (message `ServerAccess`). Logins with the system administrator server
  role have it. Users with full control of the vault have it only when the server is configured
  to let vault administrators run code. Without it, writing fails with "Editing vault
  application bindings or VBScript code requires system administrator rights.".
- When the server is configured to accept signed scripts, a vault administrator can write vault
  event handlers without `run_code`: each new or changed `code` must then carry a valid digital
  signature, and the caller needs the vault right `run_signed_code` (part of full control).
- Reading vault handlers, including their code, needs only the vault right
  `change_metadata_structure`. Reading server handlers needs `run_code`.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [GetServerEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetServerEventHandlers/index.md) | Gets all server-level event handlers, with their code. | `admin` `session` `idempotent` |
| [GetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers/index.md) | Gets all event handlers of the vault, with their code. | `admin` `session` `idempotent` |
| [SetServerEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetServerEventHandlers/index.md) | Replaces all server-level event handlers with the given list. | `admin` `session` `idempotent` |
| [SetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers/index.md) | Replaces all event handlers of the vault with the given list. | `admin` `session` `idempotent` |

---

# IRPCEventHandlersAdmin.GetServerEventHandlers

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetServerEventHandlers/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all server-level event handlers, with their code.

- **Service:** [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md) `MFiles.IRPCEventHandlersAdmin`
- **gRPC method:** `/MFiles.IRPCEventHandlersAdmin/GetServerEventHandlers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-server-event-handlers`
- **Request:** [`GetServerEventHandlersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetServerEventHandlers/index.md#request)
- **Response:** [`GetServerEventHandlersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetServerEventHandlers/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the server right `run_code`. A server-level session is enough. A vault administrator
  without `run_code` gets "Access denied. You do not have the server-level access rights
  required by this operation." (0x800400A8).

<a id="request"></a>

## Request: GetServerEventHandlersRequest

No fields.

<a id="response"></a>

## Response: GetServerEventHandlersResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`InternalEventHandler`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.InternalEventHandler/index.md) | The server-level event handlers. See [InternalEventHandler](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.InternalEventHandler/index.md). |
| `values[].event_type` | [`InternalEventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.InternalEventType/index.md) | The event type the handler is associated with. |
| `values[].sort_index` | `int32` | The sort index defines the order in which the event handlers are executed in response to an event. |
| `values[].is_active` | `bool` | True when this handler is active and is executed in response to events. |
| `values[].description` | `string` | Description of the event handler. A user friendly identifier for the event handler. |
| `values[].code` | `string` | The actual code for the event handler that is executed in response an event.. |
| `values[].guid` | `string` | GUID for the event handler. |

---

# IRPCEventHandlersAdmin.GetVaultEventHandlers

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all event handlers of the vault, with their code.

- **Service:** [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md) `MFiles.IRPCEventHandlersAdmin`
- **gRPC method:** `/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-vault-event-handlers`
- **Request:** [`GetVaultEventHandlersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers/index.md#request)
- **Response:** [`GetVaultEventHandlersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `change_metadata_structure`; a normal user gets
  "Access denied.".
- Returns active and inactive handlers, including those registered by vault applications.
- Returns an empty list when the server license does not include event handlers.

<a id="request"></a>

## Request: GetVaultEventHandlersRequest

No fields.

<a id="response"></a>

## Response: GetVaultEventHandlersResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`InternalEventHandler`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.InternalEventHandler/index.md) | The event handlers of the vault. See [InternalEventHandler](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.InternalEventHandler/index.md). |
| `values[].event_type` | [`InternalEventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.InternalEventType/index.md) | The event type the handler is associated with. |
| `values[].sort_index` | `int32` | The sort index defines the order in which the event handlers are executed in response to an event. |
| `values[].is_active` | `bool` | True when this handler is active and is executed in response to events. |
| `values[].description` | `string` | Description of the event handler. A user friendly identifier for the event handler. |
| `values[].code` | `string` | The actual code for the event handler that is executed in response an event.. |
| `values[].guid` | `string` | GUID for the event handler. |

---

# IRPCEventHandlersAdmin.SetServerEventHandlers

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetServerEventHandlers/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Replaces all server-level event handlers with the given list.

- **Service:** [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md) `MFiles.IRPCEventHandlersAdmin`
- **gRPC method:** `/MFiles.IRPCEventHandlersAdmin/SetServerEventHandlers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-server-event-handlers`
- **Request:** [`SetServerEventHandlersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetServerEventHandlers/index.md#request)
- **Response:** [`SetServerEventHandlersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetServerEventHandlers/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Replaces the whole list**: handlers that are not in `event_handlers` are removed.
- Requires the server right `run_code`; signed scripts do not replace it here. A server-level
  session is enough.
- Validation as in [SetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers/index.md),
  except that every `event_type` must be a server event. Fails when the server license does not
  include event handlers.

<a id="request"></a>

## Request: SetServerEventHandlersRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `event_handlers[]` | repeated [`InternalEventHandler`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.InternalEventHandler/index.md) | The complete new list of the server's event handlers. |
| `event_handlers[].event_type` | [`InternalEventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.InternalEventType/index.md) | The event type the handler is associated with. |
| `event_handlers[].sort_index` | `int32` | The sort index defines the order in which the event handlers are executed in response to an event. |
| `event_handlers[].is_active` | `bool` | True when this handler is active and is executed in response to events. |
| `event_handlers[].description` | `string` | Description of the event handler. A user friendly identifier for the event handler. |
| `event_handlers[].code` | `string` | The actual code for the event handler that is executed in response an event.. |
| `event_handlers[].guid` | `string` | GUID for the event handler. |

<a id="response"></a>

## Response: SetServerEventHandlersResponse

No fields.

<a id="related"></a>

## Related methods

- [SetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers/index.md): Replaces all event handlers of the vault with the given list.

---

# IRPCEventHandlersAdmin.SetVaultEventHandlers

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Replaces all event handlers of the vault with the given list.

- **Service:** [Event handlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/index.md) `MFiles.IRPCEventHandlersAdmin`
- **gRPC method:** `/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-vault-event-handlers`
- **Request:** [`SetVaultEventHandlersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers/index.md#request)
- **Response:** [`SetVaultEventHandlersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/SetVaultEventHandlers/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Replaces the whole list**: handlers that are not in `event_handlers` are removed. Get the
  current list with [GetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers/index.md)
  first and send unchanged handlers back with their `guid`.
- Requires a vault session, the vault right `change_metadata_structure`, and the right to run
  code: `run_code`, or signed scripts and `run_signed_code` (see the service overview).
- Validation: every `event_type` must be a vault event, `description` must not be empty, the
  `code` of active handlers must compile ("The VBScript code for the event handler ... is
  invalid."), and the `sort_index` values of each event type must be 0, 1, 2, ... without gaps.
- The session language must be the vault's default language; a session in another vault
  language fails with "Not implemented.". Fails also when the server license does not include
  event handlers.
- Takes effect for the vault after the call commits; when full event logging is on, the server
  logs each added, changed and removed handler.

<a id="request"></a>

## Request: SetVaultEventHandlersRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `event_handlers[]` | repeated [`InternalEventHandler`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.InternalEventHandler/index.md) | The complete new list of the vault's event handlers. Include existing handlers with their `guid`; leave `guid` empty for a new handler. |
| `event_handlers[].event_type` | [`InternalEventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.InternalEventType/index.md) | The event type the handler is associated with. |
| `event_handlers[].sort_index` | `int32` | The sort index defines the order in which the event handlers are executed in response to an event. |
| `event_handlers[].is_active` | `bool` | True when this handler is active and is executed in response to events. |
| `event_handlers[].description` | `string` | Description of the event handler. A user friendly identifier for the event handler. |
| `event_handlers[].code` | `string` | The actual code for the event handler that is executed in response an event.. |
| `event_handlers[].guid` | `string` | GUID for the event handler. |

<a id="response"></a>

## Response: SetVaultEventHandlersResponse

No fields.

<a id="related"></a>

## Related methods

- [GetVaultEventHandlers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventHandlersAdmin/GetVaultEventHandlers/index.md): Gets all event handlers of the vault, with their code.

---

# Event administration (IRPCEventsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/

Reads, exports and deletes the vault's event log, turns event logging on or off, and stores the
caller's saved event log filters.

MFAdmin uses this interface to admininistrate events.

- **gRPC service:** `MFiles.IRPCEventsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 13
- **Proto file:** [`mfiles/IRPCEventsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCEventsAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service for the vault's event log: viewing, exporting and clearing it.
Every method needs a vault session and the vault right `manage_events` (part of full control);
a normal user gets "Access denied." (0x800407E4 with reason 0x800400A9).

- **Logging on or off**:
  [IsEventLoggingEnabled](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/IsEventLoggingEnabled/index.md),
  [EnableEventLogging](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EnableEventLogging/index.md).
- **Read events** ([Event](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Event/index.md)): find the ID range with
  [GetMinAndMaxEventIDs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetMinAndMaxEventIDs/index.md), then read pages with
  [GetEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md).
- **Export and delete**: after saving the events elsewhere, record the export with
  [EventsExported](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EventsExported/index.md) and remove them with
  [DeleteEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/index.md);
  [ClearEvents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/ClearEvents/index.md) removes all events.
- **Saved filters** of the event log viewer, private to each user:
  [SaveEventLogFilter](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/SaveEventLogFilter/index.md),
  [GetEventLogFilters](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilters/index.md),
  [DeleteEventLogFilters](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventLogFilters/index.md),
  [GetEventLogFilterRecord](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilterRecord/index.md),
  [UpdateEventLogFilterDefaultValue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/UpdateEventLogFilterDefaultValue/index.md).

**Client version.** [GetEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md) and
[GetEvents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEvents/index.md) fail with "The installed M-Files client
version is older than the M-Files Server version." (0x80040930) unless the session was opened
with `client_data.version` 12.0.5192.0 or newer. Log in with `client_data.version` set to the
`server_version` from [QueryVersion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCQueryVersion/QueryVersion/index.md).

**-1 means "no filter".** Event ID bounds and object filters use -1 for "not set". The proto3
default 0 is a real value: a request left at its defaults matches no events.

**Advanced event log features** (21 CFR Part 11 compliance): when they are enabled in the vault,
event logging cannot be turned off and [ClearEvents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/ClearEvents/index.md)
is refused; [DeleteEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/index.md) still works.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [ClearEvents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/ClearEvents/index.md) | Deletes all events of the vault. | `admin` `session` |
| [DeleteEventLogFilters](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventLogFilters/index.md) | Deletes saved event log filters of the calling user by ID. | `admin` `session` `idempotent` |
| [DeleteEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/index.md) | Deletes the events whose IDs are in the given range. | `admin` `session` |
| [EnableEventLogging](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EnableEventLogging/index.md) | Turns event logging of the vault on or off. | `admin` `session` `idempotent` |
| [EventsExported](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EventsExported/index.md) | Records in the event log that a range of events was exported. | `admin` `session` |
| [GetEventLogFilterRecord](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilterRecord/index.md) | Gets the conditions of the calling user's default event log filter. | `admin` `session` `idempotent` |
| [GetEventLogFilters](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilters/index.md) | Gets the event log filters saved by the calling user. | `admin` `session` `idempotent` |
| [GetEvents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEvents/index.md) | Gets all events of the vault. | `admin` `session` |
| [GetEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md) | Gets events by ID range and filters, oldest or newest first, with an optional maximum count. | `admin` `session` `idempotent` |
| [GetMinAndMaxEventIDs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetMinAndMaxEventIDs/index.md) | Gets the smallest and largest event ID in the vault's event log. | `admin` `session` |
| [IsEventLoggingEnabled](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/IsEventLoggingEnabled/index.md) | Tells whether event logging is on in the vault. | `admin` `session` `idempotent` |
| [SaveEventLogFilter](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/SaveEventLogFilter/index.md) | Saves a named event log filter for the calling user. | `admin` `session` `idempotent` |
| [UpdateEventLogFilterDefaultValue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/UpdateEventLogFilterDefaultValue/index.md) | Makes a saved event log filter the user's default filter, or clears its default flag. | `admin` `session` `idempotent` |

---

# IRPCEventsAdmin.ClearEvents

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/ClearEvents/

Badges: `Administration API / specialized` `admin` `session`

Deletes all events of the vault.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/ClearEvents`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/clear-events`
- **Request:** [`ClearEventsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/ClearEvents/index.md#request)
- **Response:** [`ClearEventsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/ClearEvents/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Destructive.** Removes the whole event log; export it first if you need it
  ([GetEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md)).
- Runs in the background: the server first creates the pending notifications, then deletes the
  events. The call returns after about five seconds, possibly before the log is empty.
- Requires a vault session and the vault right `manage_events`. Refused in vaults with the
  advanced event log features; use
  [DeleteEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/index.md) there.

<a id="request"></a>

## Request: ClearEventsRequest

No fields.

<a id="response"></a>

## Response: ClearEventsResponse

No fields.

<a id="related"></a>

## Related methods

- [GetEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md): Gets events by ID range and filters, oldest or newest first, with an optional maximum count.
- [DeleteEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/index.md): Deletes the events whose IDs are in the given range.

---

# IRPCEventsAdmin.DeleteEventLogFilters

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventLogFilters/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Deletes saved event log filters of the calling user by ID.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/DeleteEventLogFilters`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/delete-event-log-filters`
- **Request:** [`DeleteEventLogFiltersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventLogFilters/index.md#request)
- **Response:** [`DeleteEventLogFiltersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventLogFilters/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Destructive.** Deletes the filters whose `id` is given; other fields are ignored.
- Requires a vault session and the vault right `manage_events`. Only the caller's own filters
  can be deleted: if any ID is unknown or belongs to another user, the call fails and nothing
  is deleted.

<a id="request"></a>

## Request: DeleteEventLogFiltersRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `event_log_filters` | [`EventLogFilterArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilterArray/index.md) | The filters to delete, identified by `id`. |
| `event_log_filters.event_log_filter_items[]` | repeated [`EventLogFilter`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilter/index.md) | Event Log Filter items. |
| `event_log_filters.event_log_filter_items[].id` | `int64` | ID of the Event Log Filter record. |
| `event_log_filters.event_log_filter_items[].name` | `string` | Name of the Event Log Filter record. |
| `event_log_filters.event_log_filter_items[].created_by_user_account` | `int32` | The account ID of the user who created the record |
| `event_log_filters.event_log_filter_items[].condition` | [`EventLogFilterCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilterCondition/index.md) | Information about the search conditions. |
| `event_log_filters.event_log_filter_items[].default_filter_view` | `bool` | Tells if the Event Log Filter record was set as Default Filter View. |

<a id="response"></a>

## Response: DeleteEventLogFiltersResponse

No fields.

---

# IRPCEventsAdmin.DeleteEventsRange

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/

Badges: `Administration API / specialized` `admin` `session`

Deletes the events whose IDs are in the given range.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/DeleteEventsRange`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/delete-events-range`
- **Request:** [`DeleteEventsRangeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/index.md#request)
- **Response:** [`DeleteEventsRangeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/DeleteEventsRange/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Destructive.** Set both bounds to -1 to delete all events; the defaults (0 and 0) delete
  only an event with ID 0.
- Deletes only events for which notifications have been created. Before deleting, the server
  starts notification processing and waits about five seconds; events still waiting for it
  stay.
- Adds an "event log cleared" event (`EVENT_TYPE_EVENT_LOG_CLEARED`) with the range, when event
  logging is on.
- Requires a vault session and the vault right `manage_events`. Allowed also in vaults with the
  advanced event log features.

<a id="request"></a>

## Request: DeleteEventsRangeRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `oldest_event_to_delete` | `int64` | The lowest event ID to delete, or -1 for no lower bound. |
| `newest_event_to_delete` | `int64` | The highest event ID to delete, or -1 for no upper bound. |

<a id="response"></a>

## Response: DeleteEventsRangeResponse

No fields.

---

# IRPCEventsAdmin.EnableEventLogging

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EnableEventLogging/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Turns event logging of the vault on or off.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/EnableEventLogging`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/enable-event-logging`
- **Request:** [`EnableEventLoggingRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EnableEventLogging/index.md#request)
- **Response:** [`EnableEventLoggingResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EnableEventLogging/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `manage_events`.
- Turning logging off fails with "This operation is not allowed when the advanced event log
  features are enabled." in vaults that use those features.
- Changes only future logging; existing events stay.

<a id="request"></a>

## Request: EnableEventLoggingRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `enable` | `bool` | True to turn event logging on, false to turn it off. |

<a id="response"></a>

## Response: EnableEventLoggingResponse

No fields.

---

# IRPCEventsAdmin.EventsExported

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EventsExported/

Badges: `Administration API / specialized` `admin` `session`

Records in the event log that a range of events was exported.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/EventsExported`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/events-exported`
- **Request:** [`EventsExportedRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EventsExported/index.md#request)
- **Response:** [`EventsExportedResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/EventsExported/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Exports nothing itself: it adds an "event log exported" event
  (`EVENT_TYPE_EVENT_LOG_EXPORTED`) with the given range and filters, when event logging is on.
  Call it after you have saved the events, for the audit trail.
- Requires a vault session and the vault right `manage_events`.

<a id="request"></a>

## Request: EventsExportedRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `oldest_exported_event` | `int64` | The lowest exported event ID, or -1 for no lower bound. |
| `newest_exported_event` | `int64` | The highest exported event ID, or -1 for no upper bound. |
| `object_type_filter` | `int32` | The object type the export was limited to, or -1 for none. |
| `object_idfilter` | `int32` | The object ID the export was limited to, or -1 for none. |

<a id="response"></a>

## Response: EventsExportedResponse

No fields.

---

# IRPCEventsAdmin.GetEventLogFilterRecord

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilterRecord/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the conditions of the calling user's default event log filter.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/GetEventLogFilterRecord`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-event-log-filter-record`
- **Request:** [`GetEventLogFilterRecordRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilterRecord/index.md#request)
- **Response:** [`GetEventLogFilterRecordResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilterRecord/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `manage_events`.
- When the user has no default filter, the response has `object_type` -1, `object_class` -2 and
  everything else empty.

<a id="request"></a>

## Request: GetEventLogFilterRecordRequest

A structure that specifies GetEventLogFilterRecord request payload.

No fields.

<a id="response"></a>

## Response: GetEventLogFilterRecordResponse

This is copy of EventLogFilterCondition for backwards compatibility.
Cannot use alias because alias that would require service proto to depend directly on struct proto.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `object_type` | `int32` | Object Type in Filter View. |
| `object_id` | `string` | Object ID in Filter View. |
| `object_name` | `string` | Object Name in Filter View. |
| `object_class` | `int32` | Object Class in Filter View. |
| `event_types` | [`EventTypeArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeArray/index.md) | Event Types in Filter View. |
| `event_types.event_types[]` | repeated [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The event types. |
| `event_caused_by_user` | `string` | User name in Filter View. |
| `start_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Start time in Filter View. |
| `end_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | End time in Filter View. |

---

# IRPCEventsAdmin.GetEventLogFilters

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilters/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the event log filters saved by the calling user.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/GetEventLogFilters`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-event-log-filters`
- **Request:** [`GetEventLogFiltersRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilters/index.md#request)
- **Response:** [`GetEventLogFiltersResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilters/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `manage_events`.
- Returns only the caller's own filters; empty if there are none.

<a id="request"></a>

## Request: GetEventLogFiltersRequest

No fields.

<a id="response"></a>

## Response: GetEventLogFiltersResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `event_log_filters` | [`EventLogFilterArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilterArray/index.md) | The caller's saved filters. |
| `event_log_filters.event_log_filter_items[]` | repeated [`EventLogFilter`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilter/index.md) | Event Log Filter items. |
| `event_log_filters.event_log_filter_items[].id` | `int64` | ID of the Event Log Filter record. |
| `event_log_filters.event_log_filter_items[].name` | `string` | Name of the Event Log Filter record. |
| `event_log_filters.event_log_filter_items[].created_by_user_account` | `int32` | The account ID of the user who created the record |
| `event_log_filters.event_log_filter_items[].condition` | [`EventLogFilterCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilterCondition/index.md) | Information about the search conditions. |
| `event_log_filters.event_log_filter_items[].default_filter_view` | `bool` | Tells if the Event Log Filter record was set as Default Filter View. |

---

# IRPCEventsAdmin.GetEvents

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEvents/

Badges: `Administration API / specialized` `admin` `session`

Gets all events of the vault.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/GetEvents`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-events`
- **Request:** [`GetEventsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEvents/index.md#request)
- **Response:** [`GetEventsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEvents/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Prefer [GetEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md): it pages and filters.
- In M-Files Server 26.11 the call fails with a database error ("Failed to prepare the SQL
  statement."). Use GetEventsRange.
- Requires a vault session, the vault right `manage_events`, and `client_data.version` set at
  login (see the service overview). Fails with "Your event log request exceeds the maximum data
  size." when the log is large.

<a id="request"></a>

## Request: GetEventsRequest

No fields.

<a id="response"></a>

## Response: GetEventsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `values[]` | repeated [`Event`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Event/index.md) | The events, newest first. See [Event](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Event/index.md). |
| `values[].id` | `int64` | The ID of the event. |
| `values[].type` | [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The type of the event. |
| `values[].category` | [`EventCategory`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventCategory/index.md) | The category of the event. Values: `EVENT_CATEGORY_UNDEFINED` (0), `EVENT_CATEGORY_FILE_ACCESS` (1), `EVENT_CATEGORY_OBJECT_CHANGE` (2), `EVENT_CATEGORY_NEW_OBJECT` (3), `EVENT_CATEGORY_OBJECT_OPERATION` (4), `EVENT_CATEGORY_SYSTEM` (5), `EVENT_CATEGORY_REQUEST` (6), `EVENT_CATEGORY_METADATA_STRUCTURE_CHANGE` (7), `EVENT_CATEGORY_PUBLIC_LINK` (8), `EVENT_CATEGORY_CUSTOM_EVENT` (9). |
| `values[].timestamp_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of this event. |
| `values[].caused_by_user` | `string` | The account name of the user whose activity lead to this event. If no user (this is a system operation), this is an empty string. |
| `values[].caused_by_user_full_name` | `string` | The full name of the user whose activity lead to this event. If no user (this is a system operation), this is an empty string. |
| `values[].caused_by_user_id` | `int32` | The ID of the user account whose activity lead to this event. If no user (this is a system operation), this is zero. |
| `values[].data` | [`EventTypeSpecificDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md) | Additional event type -specific data as a union. |
| `values[].data.file_accessed` | [`EventTypeSpecificDataUnion.FileAccessedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-FileAccessedData) (oneof data) |   |
| `values[].data.object_changed` | [`EventTypeSpecificDataUnion.ObjectChangedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ObjectChangedData) (oneof data) |   |
| `values[].data.object_created` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.rolled_back` | [`EventTypeSpecificDataUnion.RolledBackData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-RolledBackData) (oneof data) |   |
| `values[].data.checked_out` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.checked_in` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.checkout_undone` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.object_deleted` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) |   |
| `values[].data.object_version_destroyed` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.object_destroyed` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) |   |
| `values[].data.logged_in` | [`EventTypeSpecificDataUnion.LoggedInData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-LoggedInData) (oneof data) |   |
| `values[].data.logged_out` | [`EventTypeSpecificDataUnion.LoggedOutData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-LoggedOutData) (oneof data) |   |
| `values[].data.backup_started` | [`EventTypeSpecificDataUnion.BackupStartedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-BackupStartedData) (oneof data) |   |
| `values[].data.backup_completed` | [`EventTypeSpecificDataUnion.BackupCompletedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-BackupCompletedData) (oneof data) |   |
| `values[].data.check_in_requested` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) |   |
| `values[].data.assigned` | [`EventTypeSpecificDataUnion.AssignedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-AssignedData) (oneof data) |   |
| `values[].data.free_request` | [`EventTypeSpecificDataUnion.FreeRequestData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-FreeRequestData) (oneof data) |   |
| `values[].data.assigned_to` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.completed_by` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.assignment_approved_by` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.assignment_rejected_by` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.state_changed` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.object_notification` | [`EventTypeSpecificDataUnion.ObjectNotificationData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ObjectNotificationData) (oneof data) |   |
| `values[].data.object_undeleted` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) | Information on the concerned object. |
| `values[].data.user_added` | [`BasicUserAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserAccountInfo/index.md) (oneof data) | Information on the concerned user account. |
| `values[].data.user_changed` | [`BasicUserAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserAccountInfo/index.md) (oneof data) | Information on the concerned user account. |
| `values[].data.user_deleted` | [`BasicUserAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserAccountInfo/index.md) (oneof data) | Information on the concerned user account. |
| `values[].data.user_group_added` | [`BasicUserGroupInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserGroupInfo/index.md) (oneof data) | Information on the concerned user group. |
| `values[].data.user_group_changed` | [`BasicUserGroupInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserGroupInfo/index.md) (oneof data) | Information on the concerned user group. |
| `values[].data.user_group_deleted` | [`BasicUserGroupInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserGroupInfo/index.md) (oneof data) | Information on the concerned user group. |
| `values[].data.event_log_exported` | [`EventTypeSpecificDataUnion.EventLogExportedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-EventLogExportedData) (oneof data) |   |
| `values[].data.event_log_cleared` | [`EventTypeSpecificDataUnion.EventLogClearedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-EventLogClearedData) (oneof data) |   |
| `values[].data.vault_restored` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) (oneof data) | The basic definition of the concerned vault. |
| `values[].data.vault_created` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) (oneof data) | The basic definition of the concerned vault. |
| `values[].data.state_transition_signature_settings_added` | [`StateTransitionSignatureSettingsForEvents`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionSignatureSettingsForEvents/index.md) (oneof data) | The concerned workflow state transition settings. |
| `values[].data.state_transition_signature_settings_changed` | [`StateTransitionSignatureSettingsForEvents`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionSignatureSettingsForEvents/index.md) (oneof data) | The concerned workflow state transition settings. |
| `values[].data.state_transition_signature_settings_removed` | [`StateTransitionSignatureSettingsForEvents`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionSignatureSettingsForEvents/index.md) (oneof data) | The concerned workflow state transition settings. |
| `values[].data.vault_variable_changed` | [`EventTypeSpecificDataUnion.VaultVariableChangedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-VaultVariableChangedData) (oneof data) |   |
| `values[].data.vault_copied` | [`EventTypeSpecificDataUnion.VaultCopiedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-VaultCopiedData) (oneof data) |   |
| `values[].data.license_prevented_advanced_event_log` | [`EventTypeSpecificDataUnion.LicensePreventedAdvancedEventLogData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-LicensePreventedAdvancedEventLogData) (oneof data) |   |
| `values[].data.public_link_created` | [`EventTypeSpecificDataUnion.PublicLinkCreatedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkCreatedData) (oneof data) |   |
| `values[].data.public_link_file_downloaded` | [`EventTypeSpecificDataUnion.PublicLinkFileDownloadedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkFileDownloadedData) (oneof data) |   |
| `values[].data.public_link_deleted` | [`EventTypeSpecificDataUnion.PublicLinkDeletedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkDeletedData) (oneof data) |   |
| `values[].data.public_link_accessed` | [`EventTypeSpecificDataUnion.PublicLinkAccessedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkAccessedData) (oneof data) |   |
| `values[].data.conflict_resolved_in_favor_of_incoming_changes` | [`EventTypeSpecificDataUnion.ConflictResolvedInFavorOfIncomingChangesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ConflictResolvedInFavorOfIncomingChangesData) (oneof data) |   |
| `values[].data.conflict_resolved_in_favor_of_local_changes` | [`EventTypeSpecificDataUnion.ConflictResolvedInFavorOfLocalChangesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ConflictResolvedInFavorOfLocalChangesData) (oneof data) |   |
| `values[].data.discarded_conflict_changes_restored_as_new_version` | [`EventTypeSpecificDataUnion.DiscardedConflictChangesRestoredAsNewVersionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-DiscardedConflictChangesRestoredAsNewVersionData) (oneof data) |   |
| `values[].data.user_mentioned_in_comment` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `values[].data.vault_login_account_added` | [`BasicVaultLoginAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicVaultLoginAccountInfo/index.md) (oneof data) | Information on the concerned vault login account. |
| `values[].data.vault_login_account_changed` | [`BasicVaultLoginAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicVaultLoginAccountInfo/index.md) (oneof data) | Information on the concerned vault login account. |
| `values[].data.vault_login_account_deleted` | [`BasicVaultLoginAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicVaultLoginAccountInfo/index.md) (oneof data) | Information on the concerned vault login account. |
| `values[].data.external_link_access_type_changed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the access-type-changed event. |
| `values[].data.external_link_anyone_with_link_expiration_updated` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the anyone-with-the-link expiration-updated event. |
| `values[].data.external_link_visitors_added` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitors-added event. |
| `values[].data.external_link_visitors_removed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitors-removed event. |
| `values[].data.external_link_visitor_expiration_updated` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitor expiration-updated event. |
| `values[].data.external_link_accessed_by_visitor` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the accessed-by-visitor event. |
| `values[].data.external_link_manage_visitors_viewed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the manage-visitors-dialog-viewed event. |
| `values[].data.external_link_visitors_viewed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitors-viewed event. |
| `values[].notification_created` | `bool` | Tells if the notifications have been created. |
| `values[].notification_object_info` | [`DocumentInfoForNotifications`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DocumentInfoForNotifications/index.md) | Document info. This is valid only until the notifications have been created. |
| `values[].notification_object_info.object_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Document information. |
| `values[].notification_object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Document properties. |
| `values[].notification_object_info.acl` | [`ACLWithNames`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACLWithNames/index.md) | Document access control list. |
| `values[].notification_object_info.old_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Old document properties. Used with some events only. |
| `values[].notification_object_info.old_acl` | [`ACLWithNames`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACLWithNames/index.md) | Document access control list. Used with some events only. |
| `values[].notification_object_info.property_acls[]` | repeated [`PVACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PVACL/index.md) | ACLs for property values. |
| `values[].notification_object_info.old_property_acls[]` | repeated [`PVACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PVACL/index.md) | ACLs for old property values. |
| `values[].notification_object_info.translated_lookup_names[]` | repeated [`ItemNames`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemNames/index.md) | Translated names for lookups. |
| `values[].xml_data` | `string` | The data represented in XML. |

<a id="related"></a>

## Related methods

- [GetEventsRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md): Gets events by ID range and filters, oldest or newest first, with an optional maximum count.

---

# IRPCEventsAdmin.GetEventsRange

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets events by ID range and filters, oldest or newest first, with an optional maximum count.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/GetEventsRange`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-events-range`
- **Request:** [`GetEventsRangeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md#request)
- **Response:** [`GetEventsRangeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventsRange/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session, the vault right `manage_events`, and `client_data.version` set at
  login (see the service overview).
- **Set -1 explicitly** in `oldest_event_to_get`, `newest_event_to_get`, `object_type_filter`
  and `object_id_filter` unless you filter on them; 0 is a real value, so a default request
  returns nothing.
- Filters are combined with AND. `object_title_filter` and `event_caused_by_user` must match
  exactly (`event_caused_by_user` is the account name, as in `Event.caused_by_user`). The time
  filter applies only when both `start_time_filter` and `end_time_filter` are set.
- Events are sorted by ID: ascending, or descending with `get_newest`. To page, repeat the call
  with `oldest_event_to_get` (or `newest_event_to_get` with `get_newest`) moved past the last ID
  you received. Internal notification-matching events are never returned.
- Fails with "Your event log request exceeds the maximum data size." when the matching events
  hold more data than the vault allows in one request (512 MiB by default); narrow the range.
- `Event.notification_object_info` is filled only in vaults with the advanced event log
  features.

<a id="request"></a>

## Request: GetEventsRangeRequest

Gets the specified range of events from the vault.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `oldest_event_to_get` | `int64` | The lowest event ID to return, or -1 for no lower bound. |
| `newest_event_to_get` | `int64` | The highest event ID to return, or -1 for no upper bound. The default 0 returns nothing. |
| `max_events_to_return` | `uint32` | The maximum number of events to return; 0 for no limit. With `get_newest` the newest matching events are returned, otherwise the oldest. |
| `get_newest` | `bool` | True to return the newest matching events first (descending IDs), false for the oldest first. |
| `object_type_filter` | `int32` | Only events of objects of this object type, or -1 for all. |
| `object_id_filter` | `int32` | Only events of the object with this ID, or -1 for all. |
| `object_title_filter` | `string` | Only events of objects with exactly this title; empty for all. |
| `object_class_filter` | `int32` | Only events of objects of this class; used only when `has_class_filter` is true. |
| `has_class_filter` | `bool` | True to apply `object_class_filter`. |
| `start_time_filter` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Only events at or after this time (UTC). Used only together with `end_time_filter`. |
| `end_time_filter` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Only events at or before this time (UTC). Used only together with `start_time_filter`. |
| `event_types` | [`EventTypeArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeArray/index.md) | Only events of these types; empty for all types. |
| `event_types.event_types[]` | repeated [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The event types. |
| `event_caused_by_user` | `string` | Only events caused by this account name; empty for all. |

<a id="response"></a>

## Response: GetEventsRangeResponse

Gets the specified range of events from the vault.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `events[]` | repeated [`Event`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Event/index.md) | The matching events. See [Event](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Event/index.md). |
| `events[].id` | `int64` | The ID of the event. |
| `events[].type` | [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The type of the event. |
| `events[].category` | [`EventCategory`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventCategory/index.md) | The category of the event. Values: `EVENT_CATEGORY_UNDEFINED` (0), `EVENT_CATEGORY_FILE_ACCESS` (1), `EVENT_CATEGORY_OBJECT_CHANGE` (2), `EVENT_CATEGORY_NEW_OBJECT` (3), `EVENT_CATEGORY_OBJECT_OPERATION` (4), `EVENT_CATEGORY_SYSTEM` (5), `EVENT_CATEGORY_REQUEST` (6), `EVENT_CATEGORY_METADATA_STRUCTURE_CHANGE` (7), `EVENT_CATEGORY_PUBLIC_LINK` (8), `EVENT_CATEGORY_CUSTOM_EVENT` (9). |
| `events[].timestamp_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The timestamp of this event. |
| `events[].caused_by_user` | `string` | The account name of the user whose activity lead to this event. If no user (this is a system operation), this is an empty string. |
| `events[].caused_by_user_full_name` | `string` | The full name of the user whose activity lead to this event. If no user (this is a system operation), this is an empty string. |
| `events[].caused_by_user_id` | `int32` | The ID of the user account whose activity lead to this event. If no user (this is a system operation), this is zero. |
| `events[].data` | [`EventTypeSpecificDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md) | Additional event type -specific data as a union. |
| `events[].data.file_accessed` | [`EventTypeSpecificDataUnion.FileAccessedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-FileAccessedData) (oneof data) |   |
| `events[].data.object_changed` | [`EventTypeSpecificDataUnion.ObjectChangedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ObjectChangedData) (oneof data) |   |
| `events[].data.object_created` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.rolled_back` | [`EventTypeSpecificDataUnion.RolledBackData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-RolledBackData) (oneof data) |   |
| `events[].data.checked_out` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.checked_in` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.checkout_undone` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.object_deleted` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) |   |
| `events[].data.object_version_destroyed` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.object_destroyed` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) |   |
| `events[].data.logged_in` | [`EventTypeSpecificDataUnion.LoggedInData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-LoggedInData) (oneof data) |   |
| `events[].data.logged_out` | [`EventTypeSpecificDataUnion.LoggedOutData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-LoggedOutData) (oneof data) |   |
| `events[].data.backup_started` | [`EventTypeSpecificDataUnion.BackupStartedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-BackupStartedData) (oneof data) |   |
| `events[].data.backup_completed` | [`EventTypeSpecificDataUnion.BackupCompletedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-BackupCompletedData) (oneof data) |   |
| `events[].data.check_in_requested` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) |   |
| `events[].data.assigned` | [`EventTypeSpecificDataUnion.AssignedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-AssignedData) (oneof data) |   |
| `events[].data.free_request` | [`EventTypeSpecificDataUnion.FreeRequestData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-FreeRequestData) (oneof data) |   |
| `events[].data.assigned_to` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.completed_by` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.assignment_approved_by` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.assignment_rejected_by` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.state_changed` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.object_notification` | [`EventTypeSpecificDataUnion.ObjectNotificationData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ObjectNotificationData) (oneof data) |   |
| `events[].data.object_undeleted` | [`BasicDocInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocInfo/index.md) (oneof data) | Information on the concerned object. |
| `events[].data.user_added` | [`BasicUserAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserAccountInfo/index.md) (oneof data) | Information on the concerned user account. |
| `events[].data.user_changed` | [`BasicUserAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserAccountInfo/index.md) (oneof data) | Information on the concerned user account. |
| `events[].data.user_deleted` | [`BasicUserAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserAccountInfo/index.md) (oneof data) | Information on the concerned user account. |
| `events[].data.user_group_added` | [`BasicUserGroupInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserGroupInfo/index.md) (oneof data) | Information on the concerned user group. |
| `events[].data.user_group_changed` | [`BasicUserGroupInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserGroupInfo/index.md) (oneof data) | Information on the concerned user group. |
| `events[].data.user_group_deleted` | [`BasicUserGroupInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicUserGroupInfo/index.md) (oneof data) | Information on the concerned user group. |
| `events[].data.event_log_exported` | [`EventTypeSpecificDataUnion.EventLogExportedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-EventLogExportedData) (oneof data) |   |
| `events[].data.event_log_cleared` | [`EventTypeSpecificDataUnion.EventLogClearedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-EventLogClearedData) (oneof data) |   |
| `events[].data.vault_restored` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) (oneof data) | The basic definition of the concerned vault. |
| `events[].data.vault_created` | [`VaultBasic`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultBasic/index.md) (oneof data) | The basic definition of the concerned vault. |
| `events[].data.state_transition_signature_settings_added` | [`StateTransitionSignatureSettingsForEvents`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionSignatureSettingsForEvents/index.md) (oneof data) | The concerned workflow state transition settings. |
| `events[].data.state_transition_signature_settings_changed` | [`StateTransitionSignatureSettingsForEvents`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionSignatureSettingsForEvents/index.md) (oneof data) | The concerned workflow state transition settings. |
| `events[].data.state_transition_signature_settings_removed` | [`StateTransitionSignatureSettingsForEvents`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionSignatureSettingsForEvents/index.md) (oneof data) | The concerned workflow state transition settings. |
| `events[].data.vault_variable_changed` | [`EventTypeSpecificDataUnion.VaultVariableChangedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-VaultVariableChangedData) (oneof data) |   |
| `events[].data.vault_copied` | [`EventTypeSpecificDataUnion.VaultCopiedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-VaultCopiedData) (oneof data) |   |
| `events[].data.license_prevented_advanced_event_log` | [`EventTypeSpecificDataUnion.LicensePreventedAdvancedEventLogData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-LicensePreventedAdvancedEventLogData) (oneof data) |   |
| `events[].data.public_link_created` | [`EventTypeSpecificDataUnion.PublicLinkCreatedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkCreatedData) (oneof data) |   |
| `events[].data.public_link_file_downloaded` | [`EventTypeSpecificDataUnion.PublicLinkFileDownloadedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkFileDownloadedData) (oneof data) |   |
| `events[].data.public_link_deleted` | [`EventTypeSpecificDataUnion.PublicLinkDeletedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkDeletedData) (oneof data) |   |
| `events[].data.public_link_accessed` | [`EventTypeSpecificDataUnion.PublicLinkAccessedData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-PublicLinkAccessedData) (oneof data) |   |
| `events[].data.conflict_resolved_in_favor_of_incoming_changes` | [`EventTypeSpecificDataUnion.ConflictResolvedInFavorOfIncomingChangesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ConflictResolvedInFavorOfIncomingChangesData) (oneof data) |   |
| `events[].data.conflict_resolved_in_favor_of_local_changes` | [`EventTypeSpecificDataUnion.ConflictResolvedInFavorOfLocalChangesData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-ConflictResolvedInFavorOfLocalChangesData) (oneof data) |   |
| `events[].data.discarded_conflict_changes_restored_as_new_version` | [`EventTypeSpecificDataUnion.DiscardedConflictChangesRestoredAsNewVersionData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeSpecificDataUnion/index.md#t-DiscardedConflictChangesRestoredAsNewVersionData) (oneof data) |   |
| `events[].data.user_mentioned_in_comment` | [`BasicDocVerInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicDocVerInfo/index.md) (oneof data) |   |
| `events[].data.vault_login_account_added` | [`BasicVaultLoginAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicVaultLoginAccountInfo/index.md) (oneof data) | Information on the concerned vault login account. |
| `events[].data.vault_login_account_changed` | [`BasicVaultLoginAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicVaultLoginAccountInfo/index.md) (oneof data) | Information on the concerned vault login account. |
| `events[].data.vault_login_account_deleted` | [`BasicVaultLoginAccountInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BasicVaultLoginAccountInfo/index.md) (oneof data) | Information on the concerned vault login account. |
| `events[].data.external_link_access_type_changed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the access-type-changed event. |
| `events[].data.external_link_anyone_with_link_expiration_updated` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the anyone-with-the-link expiration-updated event. |
| `events[].data.external_link_visitors_added` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitors-added event. |
| `events[].data.external_link_visitors_removed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitors-removed event. |
| `events[].data.external_link_visitor_expiration_updated` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitor expiration-updated event. |
| `events[].data.external_link_accessed_by_visitor` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the accessed-by-visitor event. |
| `events[].data.external_link_manage_visitors_viewed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the manage-visitors-dialog-viewed event. |
| `events[].data.external_link_visitors_viewed` | [`ExternalLinkEventData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLinkEventData/index.md) (oneof data) | Shared-link data for the visitors-viewed event. |
| `events[].notification_created` | `bool` | Tells if the notifications have been created. |
| `events[].notification_object_info` | [`DocumentInfoForNotifications`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DocumentInfoForNotifications/index.md) | Document info. This is valid only until the notifications have been created. |
| `events[].notification_object_info.object_info` | [`ObjectVersionEx`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectVersionEx/index.md) | Document information. |
| `events[].notification_object_info.properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Document properties. |
| `events[].notification_object_info.acl` | [`ACLWithNames`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACLWithNames/index.md) | Document access control list. |
| `events[].notification_object_info.old_properties[]` | repeated [`PropertyValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyValue/index.md) | Old document properties. Used with some events only. |
| `events[].notification_object_info.old_acl` | [`ACLWithNames`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ACLWithNames/index.md) | Document access control list. Used with some events only. |
| `events[].notification_object_info.property_acls[]` | repeated [`PVACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PVACL/index.md) | ACLs for property values. |
| `events[].notification_object_info.old_property_acls[]` | repeated [`PVACL`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PVACL/index.md) | ACLs for old property values. |
| `events[].notification_object_info.translated_lookup_names[]` | repeated [`ItemNames`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ItemNames/index.md) | Translated names for lookups. |
| `events[].xml_data` | `string` | The data represented in XML. |
| `has_disabled_event_types_info` | `bool` | True when `disabled_event_types` is filled; always true on current servers. |
| `disabled_event_types` | [`EventTypeArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeArray/index.md) | The event types that the vault's settings exclude from logging, so their absence from the results does not mean nothing happened. |
| `disabled_event_types.event_types[]` | repeated [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The event types. |

<a id="related"></a>

## Related methods

- [GetEvents](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEvents/index.md): Gets all events of the vault.

---

# IRPCEventsAdmin.GetMinAndMaxEventIDs

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetMinAndMaxEventIDs/

Badges: `Administration API / specialized` `admin` `session`

Gets the smallest and largest event ID in the vault's event log.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/GetMinAndMaxEventIDs`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-min-and-max-event-ids`
- **Request:** [`GetMinAndMaxEventIDsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetMinAndMaxEventIDs/index.md#request)
- **Response:** [`GetMinAndMaxEventIDsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetMinAndMaxEventIDs/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `manage_events`.
- Both are 0 when the log is empty. IDs grow over time but are not contiguous: deleted events
  leave gaps.

<a id="request"></a>

## Request: GetMinAndMaxEventIDsRequest

No fields.

<a id="response"></a>

## Response: GetMinAndMaxEventIDsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `min_event_id` | `int64` | The ID of the oldest event, or 0 if there are no events. |
| `max_event_id` | `int64` | The ID of the newest event, or 0 if there are no events. |

---

# IRPCEventsAdmin.IsEventLoggingEnabled

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/IsEventLoggingEnabled/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Tells whether event logging is on in the vault.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/IsEventLoggingEnabled`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/is-event-logging-enabled`
- **Request:** [`IsEventLoggingEnabledRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/IsEventLoggingEnabled/index.md#request)
- **Response:** [`IsEventLoggingEnabledResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/IsEventLoggingEnabled/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `manage_events` (a normal user is
  denied).

<a id="request"></a>

## Request: IsEventLoggingEnabledRequest

No fields.

<a id="response"></a>

## Response: IsEventLoggingEnabledResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `enabled` | `bool` | True if the vault logs events. |

---

# IRPCEventsAdmin.SaveEventLogFilter

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/SaveEventLogFilter/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Saves a named event log filter for the calling user.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/SaveEventLogFilter`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/save-event-log-filter`
- **Request:** [`SaveEventLogFilterRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/SaveEventLogFilter/index.md#request)
- **Response:** [`SaveEventLogFilterResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/SaveEventLogFilter/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with a user account in the vault and the vault right
  `manage_events`.
- Filters are private to the user who saves them. A name that the user already has fails with
  "There is already a filtered view with the same name.", so repeating the call is not safe.
- The server assigns the ID and records the caller as creator; `id` and
  `created_by_user_account` in the request are ignored. With `default_filter_view` true, the
  user's previous default filter stops being the default.

<a id="request"></a>

## Request: SaveEventLogFilterRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `event_log_filter` | [`EventLogFilter`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilter/index.md) | The filter to save: `name`, `condition` and `default_filter_view`. See [EventLogFilter](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilter/index.md). |
| `event_log_filter.id` | `int64` | ID of the Event Log Filter record. |
| `event_log_filter.name` | `string` | Name of the Event Log Filter record. |
| `event_log_filter.created_by_user_account` | `int32` | The account ID of the user who created the record |
| `event_log_filter.condition` | [`EventLogFilterCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilterCondition/index.md) | Information about the search conditions. |
| `event_log_filter.condition.object_type` | `int32` | Object Type in Filter View. |
| `event_log_filter.condition.object_id` | `string` | Object ID in Filter View. |
| `event_log_filter.condition.object_name` | `string` | Object Name in Filter View. |
| `event_log_filter.condition.object_class` | `int32` | Object Class in Filter View. |
| `event_log_filter.condition.event_types` | [`EventTypeArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeArray/index.md) | Event Types in Filter View. |
| `event_log_filter.condition.event_caused_by_user` | `string` | User name in Filter View. |
| `event_log_filter.condition.start_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Start time in Filter View. |
| `event_log_filter.condition.end_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | End time in Filter View. |
| `event_log_filter.default_filter_view` | `bool` | Tells if the Event Log Filter record was set as Default Filter View. |

<a id="response"></a>

## Response: SaveEventLogFilterResponse

No fields.

---

# IRPCEventsAdmin.UpdateEventLogFilterDefaultValue

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/UpdateEventLogFilterDefaultValue/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Makes a saved event log filter the user's default filter, or clears its default flag.

- **Service:** [Event administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/index.md) `MFiles.IRPCEventsAdmin`
- **gRPC method:** `/MFiles.IRPCEventsAdmin/UpdateEventLogFilterDefaultValue`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/update-event-log-filter-default-value`
- **Request:** [`UpdateEventLogFilterDefaultValueRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/UpdateEventLogFilterDefaultValue/index.md#request)
- **Response:** [`UpdateEventLogFilterDefaultValueResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/UpdateEventLogFilterDefaultValue/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `manage_events`.
- Only `id` and `default_filter_view` are used. With `default_filter_view` true, the caller's
  previous default filter stops being the default. An unknown `id` is not reported as an error.

<a id="request"></a>

## Request: UpdateEventLogFilterDefaultValueRequest

This is copy of EventLogFilter for backwards compatibility.
Cannot use alias because alias that would require service proto to depend directly on struct proto.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int64` | The ID of one of your saved filters, from [GetEventLogFilters](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCEventsAdmin/GetEventLogFilters/index.md). |
| `name` | `string` | Ignored. |
| `created_by_user_account` | `int32` | Ignored. |
| `condition` | [`EventLogFilterCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventLogFilterCondition/index.md) | Ignored. |
| `condition.object_type` | `int32` | Object Type in Filter View. |
| `condition.object_id` | `string` | Object ID in Filter View. |
| `condition.object_name` | `string` | Object Name in Filter View. |
| `condition.object_class` | `int32` | Object Class in Filter View. |
| `condition.event_types` | [`EventTypeArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EventTypeArray/index.md) | Event Types in Filter View. |
| `condition.event_types.event_types[]` | repeated [`EventType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.EventType/index.md) | The event types. |
| `condition.event_caused_by_user` | `string` | User name in Filter View. |
| `condition.start_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | Start time in Filter View. |
| `condition.end_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | End time in Filter View. |
| `default_filter_view` | `bool` | True to make the filter the default, false to clear its default flag. |

<a id="response"></a>

## Response: UpdateEventLogFilterDefaultValueResponse

A structure that specifies UpdateEventLogFilterDefaultValue response payload.

No fields.

---

# Scheduled jobs (IRPCScheduledJobsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/

Lists, adds, changes, removes, starts and cancels scheduled jobs of the server or of a vault.

Use this interface to add, remove and modify scheduled jobs.

- **gRPC service:** `MFiles.IRPCScheduledJobsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 10
- **Proto file:** [`mfiles/IRPCScheduledJobsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCScheduledJobsAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service for scheduled jobs (backups, vault copies, verification) and for
the archiving and optimization jobs of a vault. A job is a
[ScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJob/index.md): a `type`, the job details in `data`, an `is_enabled`
flag and a `schedule`. Its state is a
[ScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobRunInfo/index.md): whether it is running, the last and
next run, errors and progress.

**Two job lists.** The session decides which jobs a call sees; their IDs are separate.

| Session | Jobs | Rights |
| --- | --- | --- |
| Server-level (`login_data.vault_guid` = null GUID) | Server jobs: backup, restore, copy vault, verify vault, recalculate property, migrate vault, encrypt file data, and optimize vault | Server right `manage_jobs` (system administrator server role) |
| Vault session | The vault's jobs: archive objects, archive old versions, restore from archive, optimize vault | Vault rights `archive` and `restore_from_archive`, or `manage_scheduled_jobs`; optimize vault jobs need `manage_scheduled_jobs` |

A server job cannot be handled in a vault session, and archiving jobs only in a session of their
vault. A vault administrator therefore manages the vault's archiving and optimization jobs but
not backups. Exceptions for server jobs: reading, starting and cancelling recalculate property
jobs, and reading verify vault jobs, do not need `manage_jobs`. Archiving jobs also need a
license that includes archiving. Missing rights fail with "Access denied.".

Typical calls: [GetScheduledJobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobs/index.md) to list,
[AddScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/AddScheduledJob/index.md) /
[ModifyScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ModifyScheduledJob/index.md) /
[RemoveScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md) to maintain,
[StartScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob/index.md) to run one now, then
poll [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md)
until `is_running` is false.

**Unset times.** In run info, "never" or "no next run" is the timestamp 1601-01-01T00:00:00Z,
not an unset field.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/AddScheduledJob/index.md) | Adds a scheduled job to the server or to the vault, depending on the job type. | `admin` `session` |
| [CancelScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md) | Asks a running scheduled job to stop. | `admin` `session` `idempotent` |
| [DownloadScheduledJobOutputFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/index.md) | Reads a block of a job output file, such as the summary of a restore from archive preview. | `admin` `session` `idempotent` |
| [GetScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob/index.md) | Gets one scheduled job and its run state. | `admin` `session` `idempotent` |
| [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md) | Gets the run state of a scheduled job: running or not, last and next run, errors and progress. | `admin` `session` `idempotent` |
| [GetScheduledJobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobs/index.md) | Gets the scheduled jobs of the server (server-level session) or of the vault (vault session), with their run state. | `admin` `session` `idempotent` |
| [ModifyScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ModifyScheduledJob/index.md) | Replaces the definition of an existing scheduled job. | `admin` `session` `idempotent` |
| [RemoveScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md) | Removes a scheduled job. | `admin` `session` |
| [ResetScheduledJobProgress](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ResetScheduledJobProgress/index.md) | Resets the saved progress of an optimize vault job, so that its next run retries the failed step or starts over. | `admin` `session` `idempotent` |
| [StartScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob/index.md) | Runs a scheduled job now, outside its schedule. | `admin` `session` `idempotent` |

---

# IRPCScheduledJobsAdmin.AddScheduledJob

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/AddScheduledJob/

Badges: `Administration API / specialized` `admin` `session`

Adds a scheduled job to the server or to the vault, depending on the job type.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/AddScheduledJob`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-scheduled-job`
- **Request:** [`AddScheduledJobRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/AddScheduledJob/index.md#request)
- **Response:** [`AddScheduledJobResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/AddScheduledJob/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- `scheduled_job.type` and the session decide where the job goes and which rights it needs
  (see the service overview): a server job needs a server-level session; archiving jobs need a
  session of their vault.
- The server assigns the ID; `scheduled_job.id` is ignored.
- Takes effect immediately: an enabled job runs on its schedule.

<a id="request"></a>

## Request: AddScheduledJobRequest

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | [`ScheduledJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJob/index.md) | The new job. `id` is ignored. |
| `scheduled_job.id` | `int32` | Job ID. |
| `scheduled_job.name` | `string` | Job name. |
| `scheduled_job.is_enabled` | `bool` | If true, the job is enabled (runs according to the specified schedule). |
| `scheduled_job.schedule` | `bytes` | The schedule of this job (a serialized Task object of Task Scheduler). |
| `scheduled_job.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `scheduled_job.data` | [`JobDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobDataUnion/index.md) | The job details as a union. |
| `scheduled_job.data.backup` | [`BackupJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackupJob/index.md) (oneof data) | Backup job. |
| `scheduled_job.data.restore` | [`RestoreJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreJob/index.md) (oneof data) | Restore job. |
| `scheduled_job.data.copy_vault` | [`CopyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CopyVaultJob/index.md) (oneof data) | Vault copying job. |
| `scheduled_job.data.verify_vault` | [`VerifyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerifyVaultJob/index.md) (oneof data) | Vault verifying job. |
| `scheduled_job.data.archive_objects` | [`ArchiveDocsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJob/index.md) (oneof data) | Archiving documents job. |
| `scheduled_job.data.archive_old_versions` | [`ArchiveOldVersionsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveOldVersionsJob/index.md) (oneof data) | Archiving old document versions job. |
| `scheduled_job.data.restore_from_archive` | [`RestoreFromArchiveJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJob/index.md) (oneof data) | Restoring documents from archive job. |
| `scheduled_job.data.optimize_vault` | [`OptimizeVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OptimizeVaultJob/index.md) (oneof data) | Optimize the vault. |
| `scheduled_job.data.recalculate_property` | [`RecalculateJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RecalculateJob/index.md) (oneof data) | Recalculate a property. |
| `scheduled_job.data.migrate_vault` | [`MigrateVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigrateVaultJob/index.md) (oneof data) | Vault migration job. |
| `scheduled_job.data.encrypt_file_data` | [`EncryptFileDataJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EncryptFileDataJob/index.md) (oneof data) | Vault file data encryption job. |
| `scheduled_job.is_temporary` | `bool` | True if the job is temporary and thus executed only once. Temporary jobs are not scheduled so their run info should not be interpreted. |

<a id="response"></a>

## Response: AddScheduledJobResponse

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new job. |
| `run_info` | [`ScheduledJobRunInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobRunInfo/index.md) | The run state of the new job. |
| `run_info.is_running` | `bool` | True if the job is currently running. |
| `run_info.next_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The next time the job will run. Zero to indicate no next run time. |
| `run_info.last_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the job ran. Zero to indicate that the job has never run (or is still running for the first time). |
| `run_info.last_run_succeeded` | `bool` | True if the last run at ftLastRun was successful, false otherwise. |
| `run_info.last_run_errors` | `string` | Error string from the last run (if any). |
| `run_info.last_run_cancelled` | `bool` | True if the job is cancelled. |
| `run_info.current_step` | `int32` | -1 or a current job step. 0 indicates the beginning. When positive, value depends on the underlying job that is being executed. Steps are numbered sequentially from 1 to forward. |
| `run_info.curent_step_completion` | `int32` | -1 or the completion percent of a current job. This is always an estimate. |
| `run_info.output` | [`ScheduledJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobOutputInfo/index.md) | The output information on the job. Available only when the job is not running (e.g. bRunning and is false). |
| `run_info.output.id` | `int32` | Job ID. |
| `run_info.output.message` | `string` | General output info message. |
| `run_info.output.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `run_info.output.data` | [`JobOutputInfoDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobOutputInfoDataUnion/index.md) | The job output info details as a union. |

---

# IRPCScheduledJobsAdmin.CancelScheduledJob

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Asks a running scheduled job to stop.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/cancel-scheduled-job`
- **Request:** [`CancelScheduledJobRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md#request)
- **Response:** [`CancelScheduledJobResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/CancelScheduledJob/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Sets the job's cancel flag and returns; the job stops asynchronously. Check
  `last_run_cancelled` with
  [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md).
- Allowed also when the vault is offline, so that a vault's optimize job can be stopped.
- Requires `manage_jobs`, or the rights for the job's type (see the service overview). An
  unknown ID fails with "Not found.".

<a id="request"></a>

## Request: CancelScheduledJobRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | `int32` | The ID of the job to cancel. |

<a id="response"></a>

## Response: CancelScheduledJobResponse

No fields.

<a id="related"></a>

## Related methods

- [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md): Gets the run state of a scheduled job: running or not, last and next run, errors and progress.

---

# IRPCScheduledJobsAdmin.DownloadScheduledJobOutputFile_ReadBlock

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Reads a block of a job output file, such as the summary of a restore from archive preview.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/download-scheduled-job-output-file_-read-block`
- **Request:** [`DownloadScheduledJobOutputFile_ReadBlockRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/index.md#request)
- **Response:** [`DownloadScheduledJobOutputFile_ReadBlockResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- The `download_id` comes from the call that produced the file, for example
  `RestoreFromArchiveResponse.download_idsummary` of
  [RestoreFromArchive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md) with `preview_only`.
- Read from offset 0 onwards until a block is shorter than requested. The server then deletes
  the download session; it also deletes it when a read fails. An unknown or finished
  `download_id` fails with "Not found. (The specified download session ... does not exist.)".
- `block_size` is at most 4 MiB. Only the session that started the download can read it.
- Requires the vault rights `archive` and `restore_from_archive`, or `manage_scheduled_jobs`
  (in a server-level session, `manage_jobs`).

<a id="request"></a>

## Request: DownloadScheduledJobOutputFile_ReadBlockRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `download_id` | `int32` | The download session ID returned by the call that produced the file. |
| `block_size` | `uint32` | The number of bytes to read, at most 4194304. |
| `offset` | `int64` | The byte offset to start reading from. |

<a id="response"></a>

## Response: DownloadScheduledJobOutputFile_ReadBlockResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `data` | `bytes` | The bytes read; shorter than `block_size` at the end of the file. |

<a id="related"></a>

## Related methods

- [IRPCVaultAdmin.RestoreFromArchive](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md): Imports the contents of an archive (or one object of it) into the vault, or previews the import.

---

# IRPCScheduledJobsAdmin.GetScheduledJob

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets one scheduled job and its run state.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-scheduled-job`
- **Request:** [`GetScheduledJobRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob/index.md#request)
- **Response:** [`GetScheduledJobResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Rights depend on the job's type (see the service overview). An unknown ID fails with "Not
  found.".

<a id="request"></a>

## Request: GetScheduledJobRequest

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | `int32` | The ID of the job. |

<a id="response"></a>

## Response: GetScheduledJobResponse

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | [`ScheduledJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJob/index.md) | The job definition. |
| `scheduled_job.id` | `int32` | Job ID. |
| `scheduled_job.name` | `string` | Job name. |
| `scheduled_job.is_enabled` | `bool` | If true, the job is enabled (runs according to the specified schedule). |
| `scheduled_job.schedule` | `bytes` | The schedule of this job (a serialized Task object of Task Scheduler). |
| `scheduled_job.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `scheduled_job.data` | [`JobDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobDataUnion/index.md) | The job details as a union. |
| `scheduled_job.data.backup` | [`BackupJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackupJob/index.md) (oneof data) | Backup job. |
| `scheduled_job.data.restore` | [`RestoreJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreJob/index.md) (oneof data) | Restore job. |
| `scheduled_job.data.copy_vault` | [`CopyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CopyVaultJob/index.md) (oneof data) | Vault copying job. |
| `scheduled_job.data.verify_vault` | [`VerifyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerifyVaultJob/index.md) (oneof data) | Vault verifying job. |
| `scheduled_job.data.archive_objects` | [`ArchiveDocsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJob/index.md) (oneof data) | Archiving documents job. |
| `scheduled_job.data.archive_old_versions` | [`ArchiveOldVersionsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveOldVersionsJob/index.md) (oneof data) | Archiving old document versions job. |
| `scheduled_job.data.restore_from_archive` | [`RestoreFromArchiveJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJob/index.md) (oneof data) | Restoring documents from archive job. |
| `scheduled_job.data.optimize_vault` | [`OptimizeVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OptimizeVaultJob/index.md) (oneof data) | Optimize the vault. |
| `scheduled_job.data.recalculate_property` | [`RecalculateJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RecalculateJob/index.md) (oneof data) | Recalculate a property. |
| `scheduled_job.data.migrate_vault` | [`MigrateVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigrateVaultJob/index.md) (oneof data) | Vault migration job. |
| `scheduled_job.data.encrypt_file_data` | [`EncryptFileDataJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EncryptFileDataJob/index.md) (oneof data) | Vault file data encryption job. |
| `scheduled_job.is_temporary` | `bool` | True if the job is temporary and thus executed only once. Temporary jobs are not scheduled so their run info should not be interpreted. |
| `run_info` | [`ScheduledJobRunInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobRunInfo/index.md) | The run state of the job. |
| `run_info.is_running` | `bool` | True if the job is currently running. |
| `run_info.next_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The next time the job will run. Zero to indicate no next run time. |
| `run_info.last_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the job ran. Zero to indicate that the job has never run (or is still running for the first time). |
| `run_info.last_run_succeeded` | `bool` | True if the last run at ftLastRun was successful, false otherwise. |
| `run_info.last_run_errors` | `string` | Error string from the last run (if any). |
| `run_info.last_run_cancelled` | `bool` | True if the job is cancelled. |
| `run_info.current_step` | `int32` | -1 or a current job step. 0 indicates the beginning. When positive, value depends on the underlying job that is being executed. Steps are numbered sequentially from 1 to forward. |
| `run_info.curent_step_completion` | `int32` | -1 or the completion percent of a current job. This is always an estimate. |
| `run_info.output` | [`ScheduledJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobOutputInfo/index.md) | The output information on the job. Available only when the job is not running (e.g. bRunning and is false). |
| `run_info.output.id` | `int32` | Job ID. |
| `run_info.output.message` | `string` | General output info message. |
| `run_info.output.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `run_info.output.data` | [`JobOutputInfoDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobOutputInfoDataUnion/index.md) | The job output info details as a union. |

<a id="related"></a>

## Related methods

- [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md): Gets the run state of a scheduled job: running or not, last and next run, errors and progress.

---

# IRPCScheduledJobsAdmin.GetScheduledJobRunInfo

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the run state of a scheduled job: running or not, last and next run, errors and progress.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-scheduled-job-run-info`
- **Request:** [`GetScheduledJobRunInfoRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md#request)
- **Response:** [`GetScheduledJobRunInfoResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Use it to poll a job after
  [StartScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob/index.md).
- Allowed also when the vault is offline. Requires `manage_jobs` or the rights for the job's
  type (see the service overview). An unknown ID fails with "Not found.".

<a id="request"></a>

## Request: GetScheduledJobRunInfoRequest

A structure that specifies the request type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | `int32` | The ID of the job. |

<a id="response"></a>

## Response: GetScheduledJobRunInfoResponse

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job_run_info` | [`ScheduledJobRunInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobRunInfo/index.md) | The run state of the job. |
| `scheduled_job_run_info.is_running` | `bool` | True if the job is currently running. |
| `scheduled_job_run_info.next_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The next time the job will run. Zero to indicate no next run time. |
| `scheduled_job_run_info.last_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the job ran. Zero to indicate that the job has never run (or is still running for the first time). |
| `scheduled_job_run_info.last_run_succeeded` | `bool` | True if the last run at ftLastRun was successful, false otherwise. |
| `scheduled_job_run_info.last_run_errors` | `string` | Error string from the last run (if any). |
| `scheduled_job_run_info.last_run_cancelled` | `bool` | True if the job is cancelled. |
| `scheduled_job_run_info.current_step` | `int32` | -1 or a current job step. 0 indicates the beginning. When positive, value depends on the underlying job that is being executed. Steps are numbered sequentially from 1 to forward. |
| `scheduled_job_run_info.curent_step_completion` | `int32` | -1 or the completion percent of a current job. This is always an estimate. |
| `scheduled_job_run_info.output` | [`ScheduledJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobOutputInfo/index.md) | The output information on the job. Available only when the job is not running (e.g. bRunning and is false). |
| `scheduled_job_run_info.output.id` | `int32` | Job ID. |
| `scheduled_job_run_info.output.message` | `string` | General output info message. |
| `scheduled_job_run_info.output.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `scheduled_job_run_info.output.data` | [`JobOutputInfoDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobOutputInfoDataUnion/index.md) | The job output info details as a union. |

<a id="related"></a>

## Related methods

- [StartScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob/index.md): Runs a scheduled job now, outside its schedule.
- [GetScheduledJob](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJob/index.md): Gets one scheduled job and its run state.

---

# IRPCScheduledJobsAdmin.GetScheduledJobs

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobs/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the scheduled jobs of the server (server-level session) or of the vault (vault session),
with their run state.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobs`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-scheduled-jobs`
- **Request:** [`GetScheduledJobsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobs/index.md#request)
- **Response:** [`GetScheduledJobsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobs/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Returns only the jobs the caller has rights to; fails with "Access denied." if it has rights
  to none. Temporary jobs are not included.
- In a vault session, optimize vault jobs are returned only if the session was opened with
  `client_data.capabilities.vault_level_optimization_jobs` true.
- Allowed also when the vault is offline.

<a id="request"></a>

## Request: GetScheduledJobsRequest

No fields.

<a id="response"></a>

## Response: GetScheduledJobsResponse

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `jobs[]` | repeated [`ScheduledJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJob/index.md) | The scheduled jobs. |
| `jobs[].id` | `int32` | Job ID. |
| `jobs[].name` | `string` | Job name. |
| `jobs[].is_enabled` | `bool` | If true, the job is enabled (runs according to the specified schedule). |
| `jobs[].schedule` | `bytes` | The schedule of this job (a serialized Task object of Task Scheduler). |
| `jobs[].type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `jobs[].data` | [`JobDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobDataUnion/index.md) | The job details as a union. |
| `jobs[].data.backup` | [`BackupJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackupJob/index.md) (oneof data) | Backup job. |
| `jobs[].data.restore` | [`RestoreJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreJob/index.md) (oneof data) | Restore job. |
| `jobs[].data.copy_vault` | [`CopyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CopyVaultJob/index.md) (oneof data) | Vault copying job. |
| `jobs[].data.verify_vault` | [`VerifyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerifyVaultJob/index.md) (oneof data) | Vault verifying job. |
| `jobs[].data.archive_objects` | [`ArchiveDocsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJob/index.md) (oneof data) | Archiving documents job. |
| `jobs[].data.archive_old_versions` | [`ArchiveOldVersionsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveOldVersionsJob/index.md) (oneof data) | Archiving old document versions job. |
| `jobs[].data.restore_from_archive` | [`RestoreFromArchiveJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJob/index.md) (oneof data) | Restoring documents from archive job. |
| `jobs[].data.optimize_vault` | [`OptimizeVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OptimizeVaultJob/index.md) (oneof data) | Optimize the vault. |
| `jobs[].data.recalculate_property` | [`RecalculateJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RecalculateJob/index.md) (oneof data) | Recalculate a property. |
| `jobs[].data.migrate_vault` | [`MigrateVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigrateVaultJob/index.md) (oneof data) | Vault migration job. |
| `jobs[].data.encrypt_file_data` | [`EncryptFileDataJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EncryptFileDataJob/index.md) (oneof data) | Vault file data encryption job. |
| `jobs[].is_temporary` | `bool` | True if the job is temporary and thus executed only once. Temporary jobs are not scheduled so their run info should not be interpreted. |
| `run_infos[]` | repeated [`ScheduledJobRunInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobRunInfo/index.md) | The run state of each job, at the same index as in `jobs`. |
| `run_infos[].is_running` | `bool` | True if the job is currently running. |
| `run_infos[].next_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The next time the job will run. Zero to indicate no next run time. |
| `run_infos[].last_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the job ran. Zero to indicate that the job has never run (or is still running for the first time). |
| `run_infos[].last_run_succeeded` | `bool` | True if the last run at ftLastRun was successful, false otherwise. |
| `run_infos[].last_run_errors` | `string` | Error string from the last run (if any). |
| `run_infos[].last_run_cancelled` | `bool` | True if the job is cancelled. |
| `run_infos[].current_step` | `int32` | -1 or a current job step. 0 indicates the beginning. When positive, value depends on the underlying job that is being executed. Steps are numbered sequentially from 1 to forward. |
| `run_infos[].curent_step_completion` | `int32` | -1 or the completion percent of a current job. This is always an estimate. |
| `run_infos[].output` | [`ScheduledJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobOutputInfo/index.md) | The output information on the job. Available only when the job is not running (e.g. bRunning and is false). |
| `run_infos[].output.id` | `int32` | Job ID. |
| `run_infos[].output.message` | `string` | General output info message. |
| `run_infos[].output.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `run_infos[].output.data` | [`JobOutputInfoDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobOutputInfoDataUnion/index.md) | The job output info details as a union. |

---

# IRPCScheduledJobsAdmin.ModifyScheduledJob

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ModifyScheduledJob/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Replaces the definition of an existing scheduled job.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/ModifyScheduledJob`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-scheduled-job`
- **Request:** [`ModifyScheduledJobRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ModifyScheduledJob/index.md#request)
- **Response:** [`ModifyScheduledJobResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ModifyScheduledJob/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- The job is identified by `scheduled_job.id`; the whole definition is replaced.
- Rights depend on the job's type (see the service overview).

<a id="request"></a>

## Request: ModifyScheduledJobRequest

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | [`ScheduledJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJob/index.md) | The complete new definition of the job, with its `id`. |
| `scheduled_job.id` | `int32` | Job ID. |
| `scheduled_job.name` | `string` | Job name. |
| `scheduled_job.is_enabled` | `bool` | If true, the job is enabled (runs according to the specified schedule). |
| `scheduled_job.schedule` | `bytes` | The schedule of this job (a serialized Task object of Task Scheduler). |
| `scheduled_job.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `scheduled_job.data` | [`JobDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobDataUnion/index.md) | The job details as a union. |
| `scheduled_job.data.backup` | [`BackupJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackupJob/index.md) (oneof data) | Backup job. |
| `scheduled_job.data.restore` | [`RestoreJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreJob/index.md) (oneof data) | Restore job. |
| `scheduled_job.data.copy_vault` | [`CopyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CopyVaultJob/index.md) (oneof data) | Vault copying job. |
| `scheduled_job.data.verify_vault` | [`VerifyVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VerifyVaultJob/index.md) (oneof data) | Vault verifying job. |
| `scheduled_job.data.archive_objects` | [`ArchiveDocsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJob/index.md) (oneof data) | Archiving documents job. |
| `scheduled_job.data.archive_old_versions` | [`ArchiveOldVersionsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveOldVersionsJob/index.md) (oneof data) | Archiving old document versions job. |
| `scheduled_job.data.restore_from_archive` | [`RestoreFromArchiveJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJob/index.md) (oneof data) | Restoring documents from archive job. |
| `scheduled_job.data.optimize_vault` | [`OptimizeVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OptimizeVaultJob/index.md) (oneof data) | Optimize the vault. |
| `scheduled_job.data.recalculate_property` | [`RecalculateJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RecalculateJob/index.md) (oneof data) | Recalculate a property. |
| `scheduled_job.data.migrate_vault` | [`MigrateVaultJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MigrateVaultJob/index.md) (oneof data) | Vault migration job. |
| `scheduled_job.data.encrypt_file_data` | [`EncryptFileDataJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EncryptFileDataJob/index.md) (oneof data) | Vault file data encryption job. |
| `scheduled_job.is_temporary` | `bool` | True if the job is temporary and thus executed only once. Temporary jobs are not scheduled so their run info should not be interpreted. |

<a id="response"></a>

## Response: ModifyScheduledJobResponse

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `run_info` | [`ScheduledJobRunInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobRunInfo/index.md) | The run state of the job after the change. |
| `run_info.is_running` | `bool` | True if the job is currently running. |
| `run_info.next_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The next time the job will run. Zero to indicate no next run time. |
| `run_info.last_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the job ran. Zero to indicate that the job has never run (or is still running for the first time). |
| `run_info.last_run_succeeded` | `bool` | True if the last run at ftLastRun was successful, false otherwise. |
| `run_info.last_run_errors` | `string` | Error string from the last run (if any). |
| `run_info.last_run_cancelled` | `bool` | True if the job is cancelled. |
| `run_info.current_step` | `int32` | -1 or a current job step. 0 indicates the beginning. When positive, value depends on the underlying job that is being executed. Steps are numbered sequentially from 1 to forward. |
| `run_info.curent_step_completion` | `int32` | -1 or the completion percent of a current job. This is always an estimate. |
| `run_info.output` | [`ScheduledJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobOutputInfo/index.md) | The output information on the job. Available only when the job is not running (e.g. bRunning and is false). |
| `run_info.output.id` | `int32` | Job ID. |
| `run_info.output.message` | `string` | General output info message. |
| `run_info.output.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `run_info.output.data` | [`JobOutputInfoDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobOutputInfoDataUnion/index.md) | The job output info details as a union. |

---

# IRPCScheduledJobsAdmin.RemoveScheduledJob

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/

Badges: `Administration API / specialized` `admin` `session`

Removes a scheduled job.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-scheduled-job`
- **Request:** [`RemoveScheduledJobRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md#request)
- **Response:** [`RemoveScheduledJobResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/RemoveScheduledJob/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Destructive.** The job definition is deleted; the job no longer runs.
- Rights depend on the job's type (see the service overview); an unknown ID fails with "Not
  found.".

<a id="request"></a>

## Request: RemoveScheduledJobRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | `int32` | The ID of the job to remove. |

<a id="response"></a>

## Response: RemoveScheduledJobResponse

No fields.

---

# IRPCScheduledJobsAdmin.ResetScheduledJobProgress

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ResetScheduledJobProgress/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Resets the saved progress of an optimize vault job, so that its next run retries the failed
step or starts over.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/ResetScheduledJobProgress`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-scheduled-job-progress`
- **Request:** [`ResetScheduledJobProgressRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ResetScheduledJobProgress/index.md#request)
- **Response:** [`ResetScheduledJobProgressResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/ResetScheduledJobProgress/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Only for optimize vault jobs (`JOB_TYPE_OPTIMIZE_VAULT`); other job types fail with "The
  parameter is incorrect.". Fails with "The job is already running." while the job runs.
- Changes only what the next run does; it does not start the job.
- Allowed also when the vault is offline. Requires `manage_jobs` or `manage_scheduled_jobs` (see
  the service overview).

<a id="request"></a>

## Request: ResetScheduledJobProgressRequest

A structure that specifies the request of the method that resets the resume progress of a scheduled job.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | `int32` | The ID of the optimize vault job. |
| `start_over` | `bool` | True to start over from the first step on the next run, false to retry the failed step. |

<a id="response"></a>

## Response: ResetScheduledJobProgressResponse

No fields.

---

# IRPCScheduledJobsAdmin.StartScheduledJob

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Runs a scheduled job now, outside its schedule.

- **Service:** [Scheduled jobs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/index.md) `MFiles.IRPCScheduledJobsAdmin`
- **gRPC method:** `/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/start-scheduled-job`
- **Request:** [`StartScheduledJobRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob/index.md#request)
- **Response:** [`StartScheduledJobResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/StartScheduledJob/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes**; follow it with
  [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md).
- Fails with "The job is already running." if it is running.
- Rights depend on the job's type (see the service overview).

<a id="request"></a>

## Request: StartScheduledJobRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job` | `int32` | The ID of the job to run. |

<a id="response"></a>

## Response: StartScheduledJobResponse

No fields.

<a id="related"></a>

## Related methods

- [GetScheduledJobRunInfo](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/GetScheduledJobRunInfo/index.md): Gets the run state of a scheduled job: running or not, last and next run, errors and progress.

---

# Background operations (IRPCBackgroundOperationsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/

Monitors the vault's background work: refreshes of external object types and external
locations, and the queue of asynchronous tasks.

Use this interface to start, stop and query background operations.

- **gRPC service:** `MFiles.IRPCBackgroundOperationsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 9
- **Proto file:** [`mfiles/IRPCBackgroundOperationsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCBackgroundOperationsAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service to show and start background refreshes and to list the vault's
asynchronous tasks. Every method needs a vault session and the vault right
`change_metadata_structure` (part of full control); a normal user gets "Access denied.". The exception is
[CheckAndRegisterMultiServerResponsibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility/index.md),
which is for an M-Files component.

**Background operations** are identified by a
[BackgroundOperationID](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackgroundOperationID/index.md): `type` and `id`. M-Files Admin uses
`BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_OBJECT_TYPE` with the object type ID and
`BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_LOCATION` with the external location ID. Start one with
[StartBackgroundOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation/index.md),
then follow it with
[GetBackgroundOperationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md)
or block with
[WaitForBackgroundOperationCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md).

**Asynchronous tasks** ([AsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTask/index.md)) are work items that the vault queues
and runs later, for example permission updates after a change (`ACLPseudoUserPropagation`,
`RefreshObjectsACL`) or preview file generation (`GenerateViewerFiles`). Task IDs grow over
time. Read them with
[GetAsyncTasksRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/index.md) or
[GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md), and wait for them with
[WaitForAsyncTaskCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md).

To wait until the vault has finished all background work queued so far (for example in a test,
after a change that triggers permission updates):

1. [QueueAndGetLatestAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask/index.md);
   stop if `is_available` is false.
2. [WaitForAsyncTaskCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md)
   with `async_tasks` = [that task's ID] and `tasks_request` = { `async_task_start`: the same ID,
   `max_count`: 50, `latest`: true, `filters`: 3 (queued or running) }.
3. Repeat step 2 with the IDs in `tasks_response.async_tasks` until it is empty.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [CheckAndRegisterMultiServerResponsibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility/index.md) | Tells whether this server is the one in a multi-server vault that runs the reporting data exports, and claims that role if no server has it. | `internal: not for applications` `admin` `session` `idempotent` |
| [GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md) | Gets one asynchronous task by ID. | `admin` `session` `idempotent` |
| [GetAsyncTasks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasks/index.md) | Gets the vault's asynchronous tasks, newest first. | `admin` `session` `idempotent` |
| [GetAsyncTasksRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/index.md) | Gets a page of asynchronous tasks, oldest or newest first, optionally only tasks in given states. | `admin` `session` `idempotent` |
| [GetBackgroundOperationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md) | Gets the run state of a background operation, such as an external object type refresh. | `admin` `session` `idempotent` |
| [QueueAndGetLatestAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask/index.md) | Gets the newest asynchronous task of the vault and asks the server to queue pending tasks for running now. | `admin` `session` `idempotent` |
| [StartBackgroundOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation/index.md) | Starts a background operation now, such as a full refresh of an external object type from its external database. | `admin` `session` `idempotent` |
| [WaitForAsyncTaskCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md) | Waits until the given asynchronous tasks have finished, then optionally returns a list of tasks. | `admin` `session` `idempotent` |
| [WaitForBackgroundOperationCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md) | Waits until a background operation has finished, or stops it. | `admin` `session` `idempotent` |

---

# IRPCBackgroundOperationsAdmin.CheckAndRegisterMultiServerResponsibility

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Tells whether this server is the one in a multi-server vault that runs the reporting data
exports, and claims that role if no server has it.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-and-register-multi-server-responsibility`
- **Request:** [`CheckAndRegisterMultiServerResponsibilityRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility/index.md#request)
- **Response:** [`CheckAndRegisterMultiServerResponsibilityResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** M-Files Reporting Data Services calls it so that only one
server of a multi-server vault runs the data exports. Applications should not call it.

- Requires a vault session and the server right `manage_jobs` (system administrator server
  role).
- On a single server it always returns true. In multi-server mode only the operation ID
  `mfdataexport` is accepted; other IDs fail with "The parameter is incorrect.".

<a id="request"></a>

## Request: CheckAndRegisterMultiServerResponsibilityRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `operation_id` | `string` | ID of the operation to check. |

<a id="response"></a>

## Response: CheckAndRegisterMultiServerResponsibilityResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `is_responsible` | `bool` | Receives true if this server machine is responsible of requested operation. |

---

# IRPCBackgroundOperationsAdmin.GetAsyncTask

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets one asynchronous task by ID.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-async-task`
- **Request:** [`GetAsyncTaskRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md#request)
- **Response:** [`GetAsyncTaskResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `change_metadata_structure`.
- An unknown ID fails with "Not found. <id>" (0x800408A4).

<a id="request"></a>

## Request: GetAsyncTaskRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `async_task` | `int64` | The ID of the task. |

<a id="response"></a>

## Response: GetAsyncTaskResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `async_task` | [`AsyncTask`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTask/index.md) | The task. |
| `async_task.id` | `int64` | Task ID. |
| `async_task.type` | `string` | Task type name. |
| `async_task.definition` | `string` | The display string of the task definition. |
| `async_task.is_running` | `bool` | True if the task is currently running. |
| `async_task.last_run_started_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran started. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_task.last_run_ended_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran ended. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_task.last_run_succeeded` | `bool` | True if the last run was successful, false otherwise. |
| `async_task.last_run_errors` | `string` | Error string from the last run (if any). |
| `async_task.canceled` | `bool` | True if the task is canceled. |
| `async_task.progress_info` | `string` | The progress info string of the task. |
| `async_task.output_info` | `string` | The output info string of the task. |

---

# IRPCBackgroundOperationsAdmin.GetAsyncTasks

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasks/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the vault's asynchronous tasks, newest first.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasks`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-async-tasks`
- **Request:** [`GetAsyncTasksRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasks/index.md#request)
- **Response:** [`GetAsyncTasksResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasks/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `change_metadata_structure`.
- Can return a very large list (up to 2,000,000 tasks). Prefer
  [GetAsyncTasksRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/index.md), which
  pages and filters.

<a id="request"></a>

## Request: GetAsyncTasksRequest

No fields.

<a id="response"></a>

## Response: GetAsyncTasksResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `async_tasks[]` | repeated [`AsyncTask`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTask/index.md) | The tasks, newest first. |
| `async_tasks[].id` | `int64` | Task ID. |
| `async_tasks[].type` | `string` | Task type name. |
| `async_tasks[].definition` | `string` | The display string of the task definition. |
| `async_tasks[].is_running` | `bool` | True if the task is currently running. |
| `async_tasks[].last_run_started_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran started. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_tasks[].last_run_ended_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran ended. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_tasks[].last_run_succeeded` | `bool` | True if the last run was successful, false otherwise. |
| `async_tasks[].last_run_errors` | `string` | Error string from the last run (if any). |
| `async_tasks[].canceled` | `bool` | True if the task is canceled. |
| `async_tasks[].progress_info` | `string` | The progress info string of the task. |
| `async_tasks[].output_info` | `string` | The output info string of the task. |

<a id="related"></a>

## Related methods

- [GetAsyncTasksRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/index.md): Gets a page of asynchronous tasks, oldest or newest first, optionally only tasks in given states.

---

# IRPCBackgroundOperationsAdmin.GetAsyncTasksRange

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets a page of asynchronous tasks, oldest or newest first, optionally only tasks in given
states.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-async-tasks-range`
- **Request:** [`GetAsyncTasksRangeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.GetAsyncTasksRangeRequest/index.md)
- **Response:** [`GetAsyncTasksRangeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.GetAsyncTasksRangeResponse/index.md)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `change_metadata_structure`.
- **Set `max_count` and `async_task_start`.** `max_count` 0 returns nothing. With `latest`, set
  `async_task_start` to -1 to start from the newest task; the default 0 returns nothing.
- With `latest`, a start ID and `filters`, the result also includes newer tasks into which
  matching older tasks were merged.
- `filters` with only unknown bits fails with "The parameter is incorrect. (Unknown filter)".

<a id="request"></a>

## Request: GetAsyncTasksRangeRequest

A structure that specifies the request type for the WaitForAsyncTaskCompletion method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `async_task_start` | `int64` | The first task ID to return, or -1 to start from the newest (`latest` true) or the oldest (`latest` false) task. |
| `max_count` | `uint32` | The maximum number of tasks to return. 0 returns nothing. |
| `latest` | `bool` | True to go from `async_task_start` towards older tasks (descending IDs), false to go towards newer tasks (ascending IDs). |
| `filters` | `uint32` | The task states to include, as a sum of bit values: 1 queued, 2 running, 4 completed successfully, 8 cancelled, 16 failed. 0 includes all tasks. |

<a id="response"></a>

## Response: GetAsyncTasksRangeResponse

A structure that specifies the response type for the WaitForAsyncTaskCompletion method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `async_tasks[]` | repeated [`AsyncTask`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTask/index.md) | The tasks, in the order given by `latest`. |
| `async_tasks[].id` | `int64` | Task ID. |
| `async_tasks[].type` | `string` | Task type name. |
| `async_tasks[].definition` | `string` | The display string of the task definition. |
| `async_tasks[].is_running` | `bool` | True if the task is currently running. |
| `async_tasks[].last_run_started_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran started. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_tasks[].last_run_ended_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran ended. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_tasks[].last_run_succeeded` | `bool` | True if the last run was successful, false otherwise. |
| `async_tasks[].last_run_errors` | `string` | Error string from the last run (if any). |
| `async_tasks[].canceled` | `bool` | True if the task is canceled. |
| `async_tasks[].progress_info` | `string` | The progress info string of the task. |
| `async_tasks[].output_info` | `string` | The output info string of the task. |

<a id="related"></a>

## Related methods

- [GetAsyncTasks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasks/index.md): Gets the vault's asynchronous tasks, newest first.

---

# IRPCBackgroundOperationsAdmin.GetBackgroundOperationStatus

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the run state of a background operation, such as an external object type refresh.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-background-operation-status`
- **Request:** [`GetBackgroundOperationStatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md#request)
- **Response:** [`GetBackgroundOperationStatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `change_metadata_structure`.
- An unknown operation fails with "Not found.".

<a id="request"></a>

## Request: GetBackgroundOperationStatusRequest

A structure that specifies the request type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `background_operation_id` | [`BackgroundOperationID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackgroundOperationID/index.md) | The operation: `type`, and `id` (the object type ID or the external location ID for the refresh types). |
| `background_operation_id.type` | [`BackgroundOperationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.BackgroundOperationType/index.md) | Operation type. Values: `BACKGROUND_OPERATION_TYPE_UNKNOWN` (0), `BACKGROUND_OPERATION_TYPE_INDEX_METADATA` (1), `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_OBJECT_TYPE` (2), `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_LOCATION` (3), `BACKGROUND_OPERATION_TYPE_PERFORM_OCR_TASK` (4), `BACKGROUND_OPERATION_TYPE_RUN_PERFORMANCE_MEASUREMENTS` (5), `BACKGROUND_OPERATION_TYPE_CLEAN_UP_ACL_DEPENDENCY_SETS` (6). |
| `background_operation_id.id` | `int32` | Specifies an ID for the operation (e.g. object type ID). |

<a id="response"></a>

## Response: GetBackgroundOperationStatusResponse

A structure that specifies the response type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `scheduled_job_run_info` | [`ScheduledJobRunInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobRunInfo/index.md) | The run state of the operation: running or not, last and next run, errors and progress. |
| `scheduled_job_run_info.is_running` | `bool` | True if the job is currently running. |
| `scheduled_job_run_info.next_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The next time the job will run. Zero to indicate no next run time. |
| `scheduled_job_run_info.last_run_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the job ran. Zero to indicate that the job has never run (or is still running for the first time). |
| `scheduled_job_run_info.last_run_succeeded` | `bool` | True if the last run at ftLastRun was successful, false otherwise. |
| `scheduled_job_run_info.last_run_errors` | `string` | Error string from the last run (if any). |
| `scheduled_job_run_info.last_run_cancelled` | `bool` | True if the job is cancelled. |
| `scheduled_job_run_info.current_step` | `int32` | -1 or a current job step. 0 indicates the beginning. When positive, value depends on the underlying job that is being executed. Steps are numbered sequentially from 1 to forward. |
| `scheduled_job_run_info.curent_step_completion` | `int32` | -1 or the completion percent of a current job. This is always an estimate. |
| `scheduled_job_run_info.output` | [`ScheduledJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ScheduledJobOutputInfo/index.md) | The output information on the job. Available only when the job is not running (e.g. bRunning and is false). |
| `scheduled_job_run_info.output.id` | `int32` | Job ID. |
| `scheduled_job_run_info.output.message` | `string` | General output info message. |
| `scheduled_job_run_info.output.type` | [`JobType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.JobType/index.md) | Job type. Values: `JOB_TYPE_UNINITIALIZED` (0), `JOB_TYPE_BACKUP` (1), `JOB_TYPE_RESTORE` (2), `JOB_TYPE_COPY_VAULT` (3), `JOB_TYPE_VERIFY_VAULT` (4), `JOB_TYPE_ARCHIVE_OBJECTS` (5), `JOB_TYPE_ARCHIVE_OLD_VERSIONS` (6), `JOB_TYPE_RESTORE_FROM_ARCHIVE` (7), `JOB_TYPE_OPTIMIZE_VAULT` (8), `JOB_TYPE_RECALCULATE_PROPERTY` (9), `JOB_TYPE_MIGRATE_VAULT` (10), `JOB_TYPE_ENCRYPT_FILE_DATA` (11). |
| `scheduled_job_run_info.output.data` | [`JobOutputInfoDataUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.JobOutputInfoDataUnion/index.md) | The job output info details as a union. |

---

# IRPCBackgroundOperationsAdmin.QueueAndGetLatestAsyncTask

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the newest asynchronous task of the vault and asks the server to queue pending tasks for
running now.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/queue-and-get-latest-async-task`
- **Request:** [`QueueAndGetLatestAsyncTaskRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask/index.md#request)
- **Response:** [`QueueAndGetLatestAsyncTaskResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `change_metadata_structure`.
- When a task exists, the server queues the vault's pending tasks for running instead of
  waiting for its next scheduling round, on this server and, by broadcast, on the others.
- Use the returned ID as the starting point when waiting for background work (see the service
  overview).

<a id="request"></a>

## Request: QueueAndGetLatestAsyncTaskRequest

No fields.

<a id="response"></a>

## Response: QueueAndGetLatestAsyncTaskResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `is_available` | `bool` | True if the vault has at least one asynchronous task. |
| `async_task` | [`AsyncTask`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTask/index.md) | The newest task (highest ID). Valid only if `is_available` is true. |
| `async_task.id` | `int64` | Task ID. |
| `async_task.type` | `string` | Task type name. |
| `async_task.definition` | `string` | The display string of the task definition. |
| `async_task.is_running` | `bool` | True if the task is currently running. |
| `async_task.last_run_started_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran started. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_task.last_run_ended_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran ended. Zero to indicate that the task has never run (or is still running for the first time). |
| `async_task.last_run_succeeded` | `bool` | True if the last run was successful, false otherwise. |
| `async_task.last_run_errors` | `string` | Error string from the last run (if any). |
| `async_task.canceled` | `bool` | True if the task is canceled. |
| `async_task.progress_info` | `string` | The progress info string of the task. |
| `async_task.output_info` | `string` | The output info string of the task. |

---

# IRPCBackgroundOperationsAdmin.StartBackgroundOperation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Starts a background operation now, such as a full refresh of an external object type from its
external database.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/start-background-operation`
- **Request:** [`StartBackgroundOperationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation/index.md#request)
- **Response:** [`StartBackgroundOperationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Starts a background operation and returns before it completes** (with
  `wait_until_started`, after it has started); follow it with
  [GetBackgroundOperationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md)
  or [WaitForBackgroundOperationCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md).
- External object type refreshes are full refreshes. They fail when the object type's external
  connection is disabled; external location refreshes fail when the location is disabled.
- In a multi-server vault, a refresh may run on the server responsible for it instead of the
  one you called.
- Requires a vault session and the vault right `change_metadata_structure`.

<a id="request"></a>

## Request: StartBackgroundOperationRequest

A structure that specifies the request type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `background_operation_id` | [`BackgroundOperationID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackgroundOperationID/index.md) | The operation to start. |
| `background_operation_id.type` | [`BackgroundOperationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.BackgroundOperationType/index.md) | Operation type. Values: `BACKGROUND_OPERATION_TYPE_UNKNOWN` (0), `BACKGROUND_OPERATION_TYPE_INDEX_METADATA` (1), `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_OBJECT_TYPE` (2), `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_LOCATION` (3), `BACKGROUND_OPERATION_TYPE_PERFORM_OCR_TASK` (4), `BACKGROUND_OPERATION_TYPE_RUN_PERFORMANCE_MEASUREMENTS` (5), `BACKGROUND_OPERATION_TYPE_CLEAN_UP_ACL_DEPENDENCY_SETS` (6). |
| `background_operation_id.id` | `int32` | Specifies an ID for the operation (e.g. object type ID). |
| `restart_if_already_running` | `bool` | True to signal a new start even if the operation is already running; false to leave a running operation alone. |
| `wait_until_started` | `bool` | True to return only after the operation has actually started. Has no effect if `restart_if_already_running` is false and the operation is already running. |

<a id="response"></a>

## Response: StartBackgroundOperationResponse

No fields.

<a id="related"></a>

## Related methods

- [GetBackgroundOperationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md): Gets the run state of a background operation, such as an external object type refresh.
- [WaitForBackgroundOperationCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md): Waits until a background operation has finished, or stops it.

---

# IRPCBackgroundOperationsAdmin.WaitForAsyncTaskCompletion

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Waits until the given asynchronous tasks have finished, then optionally returns a list of tasks.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/wait-for-async-task-completion`
- **Request:** [`WaitForAsyncTaskCompletionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md#request)
- **Response:** [`WaitForAsyncTaskCompletionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Blocks without a server-side time limit**: the server checks the tasks every two seconds
  until all are done. Set a deadline on the call. The wait is cancelled with an error when the
  server shuts down or the vault goes offline.
- A task counts as done when it has completed successfully or was cancelled. When a task was
  merged into a newer task, the server waits for the newer one. When a task fails, the call fails
  with the task's error. An unknown ID fails with "Not found. <id>".
- At most 50 tasks per call, and `tasks_request.max_count` at most 50; more fail with "The
  parameter is incorrect.".
- `tasks_request` is run after the wait, so its result lists the tasks that are still queued or
  running at that point. See the waiting recipe in the service overview.
- Requires a vault session and the vault right `change_metadata_structure`.

<a id="request"></a>

## Request: WaitForAsyncTaskCompletionRequest

A structure that specifies the request type for the WaitForAsyncTaskCompletion method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `obsolete_async_task` | `int64` | Obsolete. Set 0; a non-zero ID is waited for in addition to `async_tasks`. |
| `tasks_request` | [`GetAsyncTasksRangeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.GetAsyncTasksRangeRequest/index.md) | Optional. If set, the response carries the result of this [GetAsyncTasksRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/index.md) request, run after the wait. `max_count` must be at most 50. |
| `tasks_request.async_task_start` | `int64` | The first task ID to return, or -1 to start from the newest (`latest` true) or the oldest (`latest` false) task. |
| `tasks_request.max_count` | `uint32` | The maximum number of tasks to return. 0 returns nothing. |
| `tasks_request.latest` | `bool` | True to go from `async_task_start` towards older tasks (descending IDs), false to go towards newer tasks (ascending IDs). |
| `tasks_request.filters` | `uint32` | The task states to include, as a sum of bit values: 1 queued, 2 running, 4 completed successfully, 8 cancelled, 16 failed. 0 includes all tasks. |
| `async_tasks[]` | repeated `int64` | The IDs of the tasks to wait for, at most 50. |

<a id="response"></a>

## Response: WaitForAsyncTaskCompletionResponse

A structure that specifies the response type for the WaitForAsyncTaskCompletion method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `tasks_response` | [`GetAsyncTasksRangeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.GetAsyncTasksRangeResponse/index.md) | The result of `tasks_request`; unset if the request had none. |
| `tasks_response.async_tasks[]` | repeated [`AsyncTask`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTask/index.md) | The tasks, in the order given by `latest`. |
| `tasks_response.async_tasks[].id` | `int64` | Task ID. |
| `tasks_response.async_tasks[].type` | `string` | Task type name. |
| `tasks_response.async_tasks[].definition` | `string` | The display string of the task definition. |
| `tasks_response.async_tasks[].is_running` | `bool` | True if the task is currently running. |
| `tasks_response.async_tasks[].last_run_started_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran started. Zero to indicate that the task has never run (or is still running for the first time). |
| `tasks_response.async_tasks[].last_run_ended_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The last time the task ran ended. Zero to indicate that the task has never run (or is still running for the first time). |
| `tasks_response.async_tasks[].last_run_succeeded` | `bool` | True if the last run was successful, false otherwise. |
| `tasks_response.async_tasks[].last_run_errors` | `string` | Error string from the last run (if any). |
| `tasks_response.async_tasks[].canceled` | `bool` | True if the task is canceled. |
| `tasks_response.async_tasks[].progress_info` | `string` | The progress info string of the task. |
| `tasks_response.async_tasks[].output_info` | `string` | The output info string of the task. |

---

# IRPCBackgroundOperationsAdmin.WaitForBackgroundOperationCompletion

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Waits until a background operation has finished, or stops it.

- **Service:** [Background operations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/index.md) `MFiles.IRPCBackgroundOperationsAdmin`
- **gRPC method:** `/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/wait-for-background-operation-completion`
- **Request:** [`WaitForBackgroundOperationCompletionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md#request)
- **Response:** [`WaitForBackgroundOperationCompletionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Returns immediately if the operation is not running. Otherwise blocks until it finishes; set
  a deadline on the call.
- With `force_stop`, the operation is asked to stop as soon as possible.
- Requires a vault session and the vault right `change_metadata_structure`.

<a id="request"></a>

## Request: WaitForBackgroundOperationCompletionRequest

A structure that specifies the request type for the corresponding method.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `background_operation_id` | [`BackgroundOperationID`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackgroundOperationID/index.md) | The operation to wait for. |
| `background_operation_id.type` | [`BackgroundOperationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.BackgroundOperationType/index.md) | Operation type. Values: `BACKGROUND_OPERATION_TYPE_UNKNOWN` (0), `BACKGROUND_OPERATION_TYPE_INDEX_METADATA` (1), `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_OBJECT_TYPE` (2), `BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_LOCATION` (3), `BACKGROUND_OPERATION_TYPE_PERFORM_OCR_TASK` (4), `BACKGROUND_OPERATION_TYPE_RUN_PERFORMANCE_MEASUREMENTS` (5), `BACKGROUND_OPERATION_TYPE_CLEAN_UP_ACL_DEPENDENCY_SETS` (6). |
| `background_operation_id.id` | `int32` | Specifies an ID for the operation (e.g. object type ID). |
| `force_stop` | `bool` | True to stop the operation as soon as possible, false to let it finish. |

<a id="response"></a>

## Response: WaitForBackgroundOperationCompletionResponse

No fields.

---

# Exported data set administration (IRPCExportedDataSetsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/

Manages the vault's exported data sets: the definitions of the vault data that M-Files Reporting
Data Services exports to a reporting database.

MFAdmin uses this interface to manage the data set configuration.

- **gRPC service:** `MFiles.IRPCExportedDataSetsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 9
- **Proto file:** [`mfiles/IRPCExportedDataSetsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCExportedDataSetsAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service for the reporting and data export settings of a vault. An
exported data set ([ExportedDataSetAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSetAdmin/index.md)) names the object
types, properties and filters to export, a schedule, and the OLE DB connection string of the
target database. M-Files Reporting Data Services runs the exports; this service only stores the
definitions, requests runs, and reads their status.

- **Definitions**: [GetExportedDataSetsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetsAdmin/index.md),
  [AddNewExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/AddNewExportedDataSet/index.md),
  [ModifyExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/ModifyExportedDataSet/index.md),
  [RemoveExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/RemoveExportedDataSet/index.md).
- **Runs**: [TriggerExportedDataSetExecution](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/TriggerExportedDataSetExecution/index.md),
  [CancelExportedDataSetExecution](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/CancelExportedDataSetExecution/index.md),
  [GetExportedDataSetExecutionStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus/index.md).
- **Report access account**:
  [GetReportAccessCredentialsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetReportAccessCredentialsAdmin/index.md),
  [SetReportAccessCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/SetReportAccessCredentials/index.md).

**Rights.** All methods need a vault session and a server license that includes the reporting
module ("This operation requires the reporting module." otherwise), except that
[GetExportedDataSetsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetsAdmin/index.md)
returns an empty list without it. Most methods need the vault right `see_all_objects`. The
connection string makes the server connect to a data source with its own service account, so
setting a new one needs the server right `run_code`, which a vault administrator normally does
not have (see [AddNewExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/AddNewExportedDataSet/index.md)).
Users without administrator rights can request a run with
[TriggerExportedDataSetRefresh](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSets/TriggerExportedDataSetRefresh/index.md)
if they have the vault right `trigger_data_export`.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddNewExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/AddNewExportedDataSet/index.md) | Adds an exported data set. | `admin` `session` |
| [CancelExportedDataSetExecution](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/CancelExportedDataSetExecution/index.md) | Requests that a running export of an exported data set stops. | `admin` `session` `idempotent` |
| [GetExportedDataSetExecutionStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus/index.md) | Gets the progress and status of the latest export run of an exported data set. | `admin` `session` `idempotent` |
| [GetExportedDataSetsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetsAdmin/index.md) | Gets all exported data sets of the vault. | `admin` `session` `idempotent` |
| [GetReportAccessCredentialsAdmin](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetReportAccessCredentialsAdmin/index.md) | Gets the account that is used to access reports generated from the exported data. | `admin` `session` `idempotent` |
| [ModifyExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/ModifyExportedDataSet/index.md) | Replaces the definition of an exported data set. | `admin` `session` `idempotent` |
| [RemoveExportedDataSet](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/RemoveExportedDataSet/index.md) | Removes an exported data set. | `admin` `session` |
| [SetReportAccessCredentials](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/SetReportAccessCredentials/index.md) | Sets the account that is used to access reports generated from the exported data. | `admin` `session` `idempotent` |
| [TriggerExportedDataSetExecution](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/TriggerExportedDataSetExecution/index.md) | Requests an immediate export run of an exported data set. | `admin` `session` `idempotent` |

---

# IRPCExportedDataSetsAdmin.AddNewExportedDataSet

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/AddNewExportedDataSet/

Badges: `Administration API / specialized` `admin` `session`

Adds an exported data set.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/AddNewExportedDataSet`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-new-exported-data-set`
- **Request:** [`AddNewExportedDataSetRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/AddNewExportedDataSet/index.md#request)
- **Response:** [`AddNewExportedDataSetResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/AddNewExportedDataSet/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session, the vault right `see_all_objects`, and the server right `run_code`:
  a caller without `run_code` cannot set a connection string, so the call fails with "Access
  denied." for it.
- The server assigns the ID; `dataset.id` is ignored.

<a id="request"></a>

## Request: AddNewExportedDataSetRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `expdataset` | [`ExportedDataSetAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSetAdmin/index.md) | The new data set. `dataset.id` is ignored. |
| `expdataset.dataset` | [`ExportedDataSet`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md) | The non-admin version of the struct. |
| `expdataset.dataset.id` | `int32` | Exported data set ID. |
| `expdataset.dataset.name` | `string` | The name of the data set. |
| `expdataset.dataset.object_types[]` | repeated [`ExportedDataObjectType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataObjectType/index.md) | Root nodes representing an object type. |
| `expdataset.dataset.options` | [`EXPORTEDDATASETFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXPORTEDDATASETFLAGS/index.md) | Data set flags. |
| `expdataset.dataset.schedule` | `bytes` | The schedule of this data set extraction (a serialized Task object of Task Scheduler). |
| `expdataset.dataset.database_connection_string` | `string` | The database connection string. |
| `expdataset.dataset.run_as_user_id` | `int32` | "Run as" user id for the exported data set. |
| `expdataset.dataset.database_schema` | [`ExportedDataSetDBSchema`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExportedDataSetDBSchema/index.md) | The database schema. Values: `EXPORTED_DATA_SET_DBSCHEMA_GENERIC` (0). |
| `expdataset.aliases` | `string` | Semicolon-separated list of semantic aliases. |

<a id="response"></a>

## Response: AddNewExportedDataSetResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `result` | [`ExportedDataSetAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSetAdmin/index.md) | The stored data set, with its new `dataset.id`. |
| `result.dataset` | [`ExportedDataSet`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md) | The non-admin version of the struct. |
| `result.dataset.id` | `int32` | Exported data set ID. |
| `result.dataset.name` | `string` | The name of the data set. |
| `result.dataset.object_types[]` | repeated [`ExportedDataObjectType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataObjectType/index.md) | Root nodes representing an object type. |
| `result.dataset.options` | [`EXPORTEDDATASETFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXPORTEDDATASETFLAGS/index.md) | Data set flags. |
| `result.dataset.schedule` | `bytes` | The schedule of this data set extraction (a serialized Task object of Task Scheduler). |
| `result.dataset.database_connection_string` | `string` | The database connection string. |
| `result.dataset.run_as_user_id` | `int32` | "Run as" user id for the exported data set. |
| `result.dataset.database_schema` | [`ExportedDataSetDBSchema`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExportedDataSetDBSchema/index.md) | The database schema. Values: `EXPORTED_DATA_SET_DBSCHEMA_GENERIC` (0). |
| `result.aliases` | `string` | Semicolon-separated list of semantic aliases. |

---

# IRPCExportedDataSetsAdmin.CancelExportedDataSetExecution

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/CancelExportedDataSetExecution/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Requests that a running export of an exported data set stops.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/CancelExportedDataSetExecution`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/cancel-exported-data-set-execution`
- **Request:** [`CancelExportedDataSetExecutionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/CancelExportedDataSetExecution/index.md#request)
- **Response:** [`CancelExportedDataSetExecutionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/CancelExportedDataSetExecution/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Records the cancel request and returns; M-Files Reporting Data Services stops the run.
- Fails when the data set is disabled. An unknown ID fails with "Not found.".
- Requires a vault session and the vault right `see_all_objects`.

<a id="request"></a>

## Request: CancelExportedDataSetExecutionRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the data set whose run to cancel. |

<a id="response"></a>

## Response: CancelExportedDataSetExecutionResponse

No fields.

---

# IRPCExportedDataSetsAdmin.GetExportedDataSetExecutionStatus

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the progress and status of the latest export run of an exported data set.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-exported-data-set-execution-status`
- **Request:** [`GetExportedDataSetExecutionStatusRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus/index.md#request)
- **Response:** [`GetExportedDataSetExecutionStatusResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `see_all_objects`. An unknown ID fails with
  "Not found.".

<a id="request"></a>

## Request: GetExportedDataSetExecutionStatusRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the data set. |

<a id="response"></a>

## Response: GetExportedDataSetExecutionStatusResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `progress_percent` | `int32` | The progress of the current run, 0-100. |
| `status_explanation` | `string` | The current status; the error message if the run failed. |
| `status_time` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | When the status was last updated. |

---

# IRPCExportedDataSetsAdmin.GetExportedDataSetsAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetsAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all exported data sets of the vault.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetsAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-exported-data-sets-admin`
- **Request:** [`GetExportedDataSetsAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetsAdmin/index.md#request)
- **Response:** [`GetExportedDataSetsAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetsAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires only a vault session: any user can call it. The
  `database_connection_string` of each data set is empty unless the caller has the vault right
  `see_all_objects`.
- Returns an empty list when the server license does not include the reporting module.

<a id="request"></a>

## Request: GetExportedDataSetsAdminRequest

No fields.

<a id="response"></a>

## Response: GetExportedDataSetsAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `results[]` | repeated [`ExportedDataSetAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSetAdmin/index.md) | The exported data sets. |
| `results[].dataset` | [`ExportedDataSet`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md) | The non-admin version of the struct. |
| `results[].dataset.id` | `int32` | Exported data set ID. |
| `results[].dataset.name` | `string` | The name of the data set. |
| `results[].dataset.object_types[]` | repeated [`ExportedDataObjectType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataObjectType/index.md) | Root nodes representing an object type. |
| `results[].dataset.options` | [`EXPORTEDDATASETFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXPORTEDDATASETFLAGS/index.md) | Data set flags. |
| `results[].dataset.schedule` | `bytes` | The schedule of this data set extraction (a serialized Task object of Task Scheduler). |
| `results[].dataset.database_connection_string` | `string` | The database connection string. |
| `results[].dataset.run_as_user_id` | `int32` | "Run as" user id for the exported data set. |
| `results[].dataset.database_schema` | [`ExportedDataSetDBSchema`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExportedDataSetDBSchema/index.md) | The database schema. Values: `EXPORTED_DATA_SET_DBSCHEMA_GENERIC` (0). |
| `results[].aliases` | `string` | Semicolon-separated list of semantic aliases. |

---

# IRPCExportedDataSetsAdmin.GetReportAccessCredentialsAdmin

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetReportAccessCredentialsAdmin/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the account that is used to access reports generated from the exported data.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/GetReportAccessCredentialsAdmin`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-report-access-credentials-admin`
- **Request:** [`GetReportAccessCredentialsAdminRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetReportAccessCredentialsAdmin/index.md#request)
- **Response:** [`GetReportAccessCredentialsAdminResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetReportAccessCredentialsAdmin/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault right `see_all_objects` (a normal user is
  denied).
- The password is not returned in clear text: `encrypted_password` is encrypted with the
  server's public key.
- When no account has been set, `type` is `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` and `account` is
  empty.

<a id="request"></a>

## Request: GetReportAccessCredentialsAdminRequest

No fields.

<a id="response"></a>

## Response: GetReportAccessCredentialsAdminResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | The report access account. |
| `impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `impersonation.encrypted_password` | `bytes` | Encrypted password. |

---

# IRPCExportedDataSetsAdmin.ModifyExportedDataSet

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/ModifyExportedDataSet/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Replaces the definition of an exported data set.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/ModifyExportedDataSet`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-exported-data-set`
- **Request:** [`ModifyExportedDataSetRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/ModifyExportedDataSet/index.md#request)
- **Response:** [`ModifyExportedDataSetResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/ModifyExportedDataSet/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- The data set is identified by `expdataset.dataset.id`; the whole definition is replaced.
- Requires a vault session and the vault right `see_all_objects`. Without the server right
  `run_code`, the connection string may change only in its credentials, and only with the vault
  right `run_signed_code` (part of full control); pointing it to another data source fails with
  "Access denied.".

<a id="request"></a>

## Request: ModifyExportedDataSetRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `expdataset` | [`ExportedDataSetAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSetAdmin/index.md) | The complete new definition, with the `dataset.id` of the data set to change. |
| `expdataset.dataset` | [`ExportedDataSet`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataSet/index.md) | The non-admin version of the struct. |
| `expdataset.dataset.id` | `int32` | Exported data set ID. |
| `expdataset.dataset.name` | `string` | The name of the data set. |
| `expdataset.dataset.object_types[]` | repeated [`ExportedDataObjectType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportedDataObjectType/index.md) | Root nodes representing an object type. |
| `expdataset.dataset.options` | [`EXPORTEDDATASETFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXPORTEDDATASETFLAGS/index.md) | Data set flags. |
| `expdataset.dataset.schedule` | `bytes` | The schedule of this data set extraction (a serialized Task object of Task Scheduler). |
| `expdataset.dataset.database_connection_string` | `string` | The database connection string. |
| `expdataset.dataset.run_as_user_id` | `int32` | "Run as" user id for the exported data set. |
| `expdataset.dataset.database_schema` | [`ExportedDataSetDBSchema`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExportedDataSetDBSchema/index.md) | The database schema. Values: `EXPORTED_DATA_SET_DBSCHEMA_GENERIC` (0). |
| `expdataset.aliases` | `string` | Semicolon-separated list of semantic aliases. |

<a id="response"></a>

## Response: ModifyExportedDataSetResponse

No fields.

---

# IRPCExportedDataSetsAdmin.RemoveExportedDataSet

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/RemoveExportedDataSet/

Badges: `Administration API / specialized` `admin` `session`

Removes an exported data set.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/RemoveExportedDataSet`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-exported-data-set`
- **Request:** [`RemoveExportedDataSetRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/RemoveExportedDataSet/index.md#request)
- **Response:** [`RemoveExportedDataSetResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/RemoveExportedDataSet/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Destructive.** Deletes the definition; already exported data in the target database is not
  touched by this call.
- Requires a vault session and the vault right `see_all_objects`. An unknown ID fails with
  "Not found.".

<a id="request"></a>

## Request: RemoveExportedDataSetRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the data set to remove. |

<a id="response"></a>

## Response: RemoveExportedDataSetResponse

No fields.

---

# IRPCExportedDataSetsAdmin.SetReportAccessCredentials

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/SetReportAccessCredentials/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Sets the account that is used to access reports generated from the exported data.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/SetReportAccessCredentials`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-report-access-credentials`
- **Request:** [`SetReportAccessCredentialsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/SetReportAccessCredentials/index.md#request)
- **Response:** [`SetReportAccessCredentialsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/SetReportAccessCredentials/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session and the vault rights `manage_users` and `see_all_objects`.
- `encrypted_password` must be encrypted with the server's public key
  ([GetPublicKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/index.md)), as M-Files Admin does.

<a id="request"></a>

## Request: SetReportAccessCredentialsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `utf8szimpersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | The account: `type`, `account` (for example `DOMAIN\user`), and `encrypted_password`. |
| `utf8szimpersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | Impersonation type. Values: `IMPERSONATION_TYPE_SYSTEM_ACCOUNT` (0), `IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT` (1), `IMPERSONATION_TYPE_EXTERNAL_ACCOUNT` (2). |
| `utf8szimpersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `utf8szimpersonation.encrypted_password` | `bytes` | Encrypted password. |

<a id="response"></a>

## Response: SetReportAccessCredentialsResponse

No fields.

<a id="related"></a>

## Related methods

- [IRPCLogin.GetPublicKey](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLogin/GetPublicKey/index.md): Gets the server's RSA public key, for encrypting secrets that a client sends to the server.

---

# IRPCExportedDataSetsAdmin.TriggerExportedDataSetExecution

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/TriggerExportedDataSetExecution/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Requests an immediate export run of an exported data set.

- **Service:** [Exported data set administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/index.md) `MFiles.IRPCExportedDataSetsAdmin`
- **gRPC method:** `/MFiles.IRPCExportedDataSetsAdmin/TriggerExportedDataSetExecution`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/trigger-exported-data-set-execution`
- **Request:** [`TriggerExportedDataSetExecutionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/TriggerExportedDataSetExecution/index.md#request)
- **Response:** [`TriggerExportedDataSetExecutionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/TriggerExportedDataSetExecution/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- **Requests a background run and returns at once**: the server records the request and M-Files
  Reporting Data Services runs the export. Follow it with
  [GetExportedDataSetExecutionStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus/index.md).
- Fails when the data set is disabled. An unknown ID fails with "Not found.".
- Requires a vault session and the vault right `see_all_objects`.

<a id="request"></a>

## Request: TriggerExportedDataSetExecutionRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the data set to export. |

<a id="response"></a>

## Response: TriggerExportedDataSetExecutionResponse

No fields.

<a id="related"></a>

## Related methods

- [GetExportedDataSetExecutionStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExportedDataSetsAdmin/GetExportedDataSetExecutionStatus/index.md): Gets the progress and status of the latest export run of an exported data set.

---

# External locations (IRPCExternalLocationsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/

Administers the vault's external sources: file folders and mail boxes from which the server
imports or links content.

Use this interface to add, modify and delete external locations in a vault.

An external location is a definition of a local or remote location
that contains files and folders. M-Files includes the files in such
a location in the document vault and monitors the location for
file additions and removals.

- **gRPC service:** `MFiles.IRPCExternalLocationsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 6
- **Proto file:** [`mfiles/IRPCExternalLocationsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCExternalLocationsAdmin.proto)

<a id="overview"></a>

## Overview

An external location ([ExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLocation/index.md)) is a file source (a
folder the server imports files from, or links them in place) or a mail source (a mail box the
server imports messages from, see `MailProtocol`). The server's background monitor checks each
location every `update_interval` seconds. M-Files Admin calls this service. The locations are
also the items of the built-in value list 5.

- **Session and rights.** Every method requires a vault session and the vault right
  `manage_external_locations`; a normal user gets "Access denied.".
  [AddExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md) and
  [ModifyExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ModifyExternalLocation/index.md) of a
  file source also require the server right `run_code` (system administrator), because the server
  reads that folder under its own account. Mail sources need only the vault right.
- **Calls**: [GetExternalLocations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/GetExternalLocations/index.md),
  [AddExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md),
  [ModifyExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ModifyExternalLocation/index.md),
  [RemoveExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RemoveExternalLocation/index.md),
  [RefreshExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RefreshExternalLocation/index.md)
  (check now) and
  [ImportFilesFromLinkedLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ImportFilesFromLinkedLocation/index.md)
  (turn linked files into imported ones).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md) | Creates an external location. | `admin` `session` |
| [GetExternalLocations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/GetExternalLocations/index.md) | Gets all external locations of the vault. | `admin` `session` `idempotent` |
| [ImportFilesFromLinkedLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ImportFilesFromLinkedLocation/index.md) | Converts a file source that links files into one that imports them, and starts importing. | `admin` `session` |
| [ModifyExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ModifyExternalLocation/index.md) | Saves a changed external location. | `admin` `session` `idempotent` |
| [RefreshExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RefreshExternalLocation/index.md) | Checks the location now instead of waiting for the next automatic round. | `admin` `session` `idempotent` |
| [RemoveExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RemoveExternalLocation/index.md) | Deletes an external location, optionally destroying the documents whose files are linked to it. | `admin` `session` |

---

# IRPCExternalLocationsAdmin.AddExternalLocation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/

Badges: `Administration API / specialized` `admin` `session`

Creates an external location.

- **Service:** [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `MFiles.IRPCExternalLocationsAdmin`
- **gRPC method:** `/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/add-external-location`
- **Request:** [`AddExternalLocationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md#request)
- **Response:** [`AddExternalLocationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `manage_external_locations`; a file source also requires the server right `run_code`.
- For a mail source without `run_code`, `update_interval` must be at least 60 seconds.
- A file source cannot both link files (`file_source.link_files`) and convert them to
  searchable PDF (`file_source.convert_to_searchable_pdf`): invalid-argument error.
- With `test_access` true, the server connects to the location and rolls the addition back if
  that fails. With false, a location that does not work yet (for example a mail server that is
  down) can be saved.

<a id="request"></a>

## Request: AddExternalLocationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `json_ext_loc` | [`ExternalLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLocation/index.md) | The new location. `id` is ignored and assigned by the server. |
| `json_ext_loc.id` | `int32` | External location ID. |
| `json_ext_loc.description` | `string` | Description. |
| `json_ext_loc.object_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | ACL for new documents. |
| `json_ext_loc.object_acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `json_ext_loc.object_acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `json_ext_loc.object_acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `json_ext_loc.object_acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `json_ext_loc.object_acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `json_ext_loc.object_acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `json_ext_loc.object_type` | `int32` | Object type. |
| `json_ext_loc.object_properties[]` | repeated [`DefaultProperty`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultProperty/index.md) | The properties. |
| `json_ext_loc.object_properties[].property_def` | `int32` | PropertyDef ID. |
| `json_ext_loc.object_properties[].allow_retaining_previous_value` | `bool` | True if the user is allowed to use/retain previous value |
| `json_ext_loc.object_properties[].type` | [`DefaultPropertyType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DefaultPropertyType/index.md) | Default property type. Values: `DEFAULT_PROPERTY_TYPE_UNDEFINED` (0), `DEFAULT_PROPERTY_TYPE_FIXED_VALUE` (1), `DEFAULT_PROPERTY_TYPE_FROM_HP_DSS_XML` (2), `DEFAULT_PROPERTY_TYPE_FROM_XML` (3), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL` (4), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL_HEADER` (5), `DEFAULT_PROPERTY_TYPE_FROM_OCR` (6), `DEFAULT_PROPERTY_TYPE_FROM_FILE_PROPERTY` (7), `DEFAULT_PROPERTY_TYPE_STATE_TRANSITION_TIME` (8). |
| `json_ext_loc.object_properties[].data` | [`DefaultPropertyUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultPropertyUnion/index.md) | The details as a union. |
| `json_ext_loc.options` | [`EXTLOCFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXTLOCFLAGS/index.md) | Flags. |
| `json_ext_loc.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `json_ext_loc.options.disabled` | `bool` | Present if the external location is disabled. If not present, the external location is enabled. |
| `json_ext_loc.options.monitor` | `bool` | Present if the server should keep monitoring the external location. |
| `json_ext_loc.update_interval` | `uint32` | The delay between automatic monitoring rounds in seconds. |
| `json_ext_loc.type` | [`ExtLocType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtLocType/index.md) | The type of the source. Values: `EXT_LOC_TYPE_NONE` (0), `EXT_LOC_TYPE_FILE_SOURCE` (1), `EXT_LOC_TYPE_MAIL_SOURCE` (2). |
| `json_ext_loc.data` | [`ExtLocUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtLocUnion/index.md) | The type-specific data as a union. |
| `json_ext_loc.data.file_source` | [`FileSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileSource/index.md) (oneof data) | File source definition. |
| `json_ext_loc.data.mail_source` | [`MailSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MailSource/index.md) (oneof data) | Mail source definition. |
| `json_ext_loc.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `test_access` | `bool` | True to test access to the external location before accepting the changes. |

<a id="response"></a>

## Response: AddExternalLocationResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the new location. |

---

# IRPCExternalLocationsAdmin.GetExternalLocations

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/GetExternalLocations/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets all external locations of the vault.

- **Service:** [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `MFiles.IRPCExternalLocationsAdmin`
- **gRPC method:** `/MFiles.IRPCExternalLocationsAdmin/GetExternalLocations`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-external-locations`
- **Request:** [`GetExternalLocationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/GetExternalLocations/index.md#request)
- **Response:** [`GetExternalLocationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/GetExternalLocations/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires `manage_external_locations`; a normal user gets "Access denied.".
- Account passwords are not returned, and the OAuth client secret of mail sources is removed.
- Returned 4 locations in the Sample Vault, 3 file sources and 1 mail source.

<a id="request"></a>

## Request: GetExternalLocationsRequest

No fields.

<a id="response"></a>

## Response: GetExternalLocationsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `json_ext_loc_array[]` | repeated [`ExternalLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLocation/index.md) | One [ExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLocation/index.md) per location. |
| `json_ext_loc_array[].id` | `int32` | External location ID. |
| `json_ext_loc_array[].description` | `string` | Description. |
| `json_ext_loc_array[].object_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | ACL for new documents. |
| `json_ext_loc_array[].object_acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `json_ext_loc_array[].object_acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `json_ext_loc_array[].object_acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `json_ext_loc_array[].object_acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `json_ext_loc_array[].object_acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `json_ext_loc_array[].object_acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `json_ext_loc_array[].object_type` | `int32` | Object type. |
| `json_ext_loc_array[].object_properties[]` | repeated [`DefaultProperty`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultProperty/index.md) | The properties. |
| `json_ext_loc_array[].object_properties[].property_def` | `int32` | PropertyDef ID. |
| `json_ext_loc_array[].object_properties[].allow_retaining_previous_value` | `bool` | True if the user is allowed to use/retain previous value |
| `json_ext_loc_array[].object_properties[].type` | [`DefaultPropertyType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DefaultPropertyType/index.md) | Default property type. Values: `DEFAULT_PROPERTY_TYPE_UNDEFINED` (0), `DEFAULT_PROPERTY_TYPE_FIXED_VALUE` (1), `DEFAULT_PROPERTY_TYPE_FROM_HP_DSS_XML` (2), `DEFAULT_PROPERTY_TYPE_FROM_XML` (3), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL` (4), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL_HEADER` (5), `DEFAULT_PROPERTY_TYPE_FROM_OCR` (6), `DEFAULT_PROPERTY_TYPE_FROM_FILE_PROPERTY` (7), `DEFAULT_PROPERTY_TYPE_STATE_TRANSITION_TIME` (8). |
| `json_ext_loc_array[].object_properties[].data` | [`DefaultPropertyUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultPropertyUnion/index.md) | The details as a union. |
| `json_ext_loc_array[].options` | [`EXTLOCFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXTLOCFLAGS/index.md) | Flags. |
| `json_ext_loc_array[].options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `json_ext_loc_array[].options.disabled` | `bool` | Present if the external location is disabled. If not present, the external location is enabled. |
| `json_ext_loc_array[].options.monitor` | `bool` | Present if the server should keep monitoring the external location. |
| `json_ext_loc_array[].update_interval` | `uint32` | The delay between automatic monitoring rounds in seconds. |
| `json_ext_loc_array[].type` | [`ExtLocType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtLocType/index.md) | The type of the source. Values: `EXT_LOC_TYPE_NONE` (0), `EXT_LOC_TYPE_FILE_SOURCE` (1), `EXT_LOC_TYPE_MAIL_SOURCE` (2). |
| `json_ext_loc_array[].data` | [`ExtLocUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtLocUnion/index.md) | The type-specific data as a union. |
| `json_ext_loc_array[].data.file_source` | [`FileSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileSource/index.md) (oneof data) | File source definition. |
| `json_ext_loc_array[].data.mail_source` | [`MailSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MailSource/index.md) (oneof data) | Mail source definition. |
| `json_ext_loc_array[].aliases` | `string` | Semicolon-separated list of semantic aliases. |

---

# IRPCExternalLocationsAdmin.ImportFilesFromLinkedLocation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ImportFilesFromLinkedLocation/

Badges: `Administration API / specialized` `admin` `session`

Converts a file source that links files into one that imports them, and starts importing.

- **Service:** [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `MFiles.IRPCExternalLocationsAdmin`
- **gRPC method:** `/MFiles.IRPCExternalLocationsAdmin/ImportFilesFromLinkedLocation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/import-files-from-linked-location`
- **Request:** [`ImportFilesFromLinkedLocationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ImportFilesFromLinkedLocation/index.md#request)
- **Response:** [`ImportFilesFromLinkedLocationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ImportFilesFromLinkedLocation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Turns off `file_source.link_files` and automatic monitoring, saves the location, and starts the
  import as a background operation; returns before it finishes.
- Only for enabled file sources: a mail source fails with an invalid-argument error.
- Restarts the server's external file monitor: running checks of all locations stop, and
  automatic checks resume in about two minutes.
- Requires `manage_external_locations`.

<a id="request"></a>

## Request: ImportFilesFromLinkedLocationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the file source. |

<a id="response"></a>

## Response: ImportFilesFromLinkedLocationResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `json_ext_loc` | [`ExternalLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLocation/index.md) | The location as saved, with linking and automatic monitoring off. |
| `json_ext_loc.id` | `int32` | External location ID. |
| `json_ext_loc.description` | `string` | Description. |
| `json_ext_loc.object_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | ACL for new documents. |
| `json_ext_loc.object_acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `json_ext_loc.object_acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `json_ext_loc.object_acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `json_ext_loc.object_acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `json_ext_loc.object_acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `json_ext_loc.object_acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `json_ext_loc.object_type` | `int32` | Object type. |
| `json_ext_loc.object_properties[]` | repeated [`DefaultProperty`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultProperty/index.md) | The properties. |
| `json_ext_loc.object_properties[].property_def` | `int32` | PropertyDef ID. |
| `json_ext_loc.object_properties[].allow_retaining_previous_value` | `bool` | True if the user is allowed to use/retain previous value |
| `json_ext_loc.object_properties[].type` | [`DefaultPropertyType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DefaultPropertyType/index.md) | Default property type. Values: `DEFAULT_PROPERTY_TYPE_UNDEFINED` (0), `DEFAULT_PROPERTY_TYPE_FIXED_VALUE` (1), `DEFAULT_PROPERTY_TYPE_FROM_HP_DSS_XML` (2), `DEFAULT_PROPERTY_TYPE_FROM_XML` (3), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL` (4), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL_HEADER` (5), `DEFAULT_PROPERTY_TYPE_FROM_OCR` (6), `DEFAULT_PROPERTY_TYPE_FROM_FILE_PROPERTY` (7), `DEFAULT_PROPERTY_TYPE_STATE_TRANSITION_TIME` (8). |
| `json_ext_loc.object_properties[].data` | [`DefaultPropertyUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultPropertyUnion/index.md) | The details as a union. |
| `json_ext_loc.options` | [`EXTLOCFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXTLOCFLAGS/index.md) | Flags. |
| `json_ext_loc.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `json_ext_loc.options.disabled` | `bool` | Present if the external location is disabled. If not present, the external location is enabled. |
| `json_ext_loc.options.monitor` | `bool` | Present if the server should keep monitoring the external location. |
| `json_ext_loc.update_interval` | `uint32` | The delay between automatic monitoring rounds in seconds. |
| `json_ext_loc.type` | [`ExtLocType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtLocType/index.md) | The type of the source. Values: `EXT_LOC_TYPE_NONE` (0), `EXT_LOC_TYPE_FILE_SOURCE` (1), `EXT_LOC_TYPE_MAIL_SOURCE` (2). |
| `json_ext_loc.data` | [`ExtLocUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtLocUnion/index.md) | The type-specific data as a union. |
| `json_ext_loc.data.file_source` | [`FileSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileSource/index.md) (oneof data) | File source definition. |
| `json_ext_loc.data.mail_source` | [`MailSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MailSource/index.md) (oneof data) | Mail source definition. |
| `json_ext_loc.aliases` | `string` | Semicolon-separated list of semantic aliases. |

---

# IRPCExternalLocationsAdmin.ModifyExternalLocation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ModifyExternalLocation/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Saves a changed external location.

- **Service:** [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `MFiles.IRPCExternalLocationsAdmin`
- **gRPC method:** `/MFiles.IRPCExternalLocationsAdmin/ModifyExternalLocation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/modify-external-location`
- **Request:** [`ModifyExternalLocationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ModifyExternalLocation/index.md#request)
- **Response:** [`ModifyExternalLocationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/ModifyExternalLocation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Same rights and rules as
  [AddExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md).
- `test_access` works as in AddExternalLocation; with false you can, for example, turn off
  automatic monitoring of a mail server that is down.

<a id="request"></a>

## Request: ModifyExternalLocationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.

| Field | Type | Description |
|---|---|---|
| `json_ext_loc` | [`ExternalLocation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExternalLocation/index.md) | The complete new location; `id` identifies it. |
| `json_ext_loc.id` | `int32` | External location ID. |
| `json_ext_loc.description` | `string` | Description. |
| `json_ext_loc.object_acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | ACL for new documents. |
| `json_ext_loc.object_acl.checked_out_to_user` | `int32` | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
| `json_ext_loc.object_acl.is_fully_authoritative` | `bool` | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
| `json_ext_loc.object_acl.custom_component` | [`AccessControlListComponent`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `json_ext_loc.object_acl.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `json_ext_loc.object_acl.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `json_ext_loc.object_acl.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `json_ext_loc.object_type` | `int32` | Object type. |
| `json_ext_loc.object_properties[]` | repeated [`DefaultProperty`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultProperty/index.md) | The properties. |
| `json_ext_loc.object_properties[].property_def` | `int32` | PropertyDef ID. |
| `json_ext_loc.object_properties[].allow_retaining_previous_value` | `bool` | True if the user is allowed to use/retain previous value |
| `json_ext_loc.object_properties[].type` | [`DefaultPropertyType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.DefaultPropertyType/index.md) | Default property type. Values: `DEFAULT_PROPERTY_TYPE_UNDEFINED` (0), `DEFAULT_PROPERTY_TYPE_FIXED_VALUE` (1), `DEFAULT_PROPERTY_TYPE_FROM_HP_DSS_XML` (2), `DEFAULT_PROPERTY_TYPE_FROM_XML` (3), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL` (4), `DEFAULT_PROPERTY_TYPE_FROM_EMAIL_HEADER` (5), `DEFAULT_PROPERTY_TYPE_FROM_OCR` (6), `DEFAULT_PROPERTY_TYPE_FROM_FILE_PROPERTY` (7), `DEFAULT_PROPERTY_TYPE_STATE_TRANSITION_TIME` (8). |
| `json_ext_loc.object_properties[].data` | [`DefaultPropertyUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DefaultPropertyUnion/index.md) | The details as a union. |
| `json_ext_loc.options` | [`EXTLOCFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.EXTLOCFLAGS/index.md) | Flags. |
| `json_ext_loc.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `json_ext_loc.options.disabled` | `bool` | Present if the external location is disabled. If not present, the external location is enabled. |
| `json_ext_loc.options.monitor` | `bool` | Present if the server should keep monitoring the external location. |
| `json_ext_loc.update_interval` | `uint32` | The delay between automatic monitoring rounds in seconds. |
| `json_ext_loc.type` | [`ExtLocType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ExtLocType/index.md) | The type of the source. Values: `EXT_LOC_TYPE_NONE` (0), `EXT_LOC_TYPE_FILE_SOURCE` (1), `EXT_LOC_TYPE_MAIL_SOURCE` (2). |
| `json_ext_loc.data` | [`ExtLocUnion`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExtLocUnion/index.md) | The type-specific data as a union. |
| `json_ext_loc.data.file_source` | [`FileSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.FileSource/index.md) (oneof data) | File source definition. |
| `json_ext_loc.data.mail_source` | [`MailSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MailSource/index.md) (oneof data) | Mail source definition. |
| `json_ext_loc.aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `test_access` | `bool` | True to test access to the external location before accepting the changes. |

<a id="response"></a>

## Response: ModifyExternalLocationResponse

No fields.

<a id="related"></a>

## Related methods

- [AddExternalLocation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/AddExternalLocation/index.md): Creates an external location.

---

# IRPCExternalLocationsAdmin.RefreshExternalLocation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RefreshExternalLocation/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Checks the location now instead of waiting for the next automatic round.

- **Service:** [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `MFiles.IRPCExternalLocationsAdmin`
- **gRPC method:** `/MFiles.IRPCExternalLocationsAdmin/RefreshExternalLocation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/refresh-external-location`
- **Request:** [`RefreshExternalLocationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RefreshExternalLocation/index.md#request)
- **Response:** [`RefreshExternalLocationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RefreshExternalLocation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Tests access to the location first and fails if the location is disabled or cannot be reached.
- Starts the refresh as a background operation and returns once it has started, not when it has
  finished.
- Requires `manage_external_locations`.

<a id="request"></a>

## Request: RefreshExternalLocationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the external location to refresh. |

<a id="response"></a>

## Response: RefreshExternalLocationResponse

No fields.

---

# IRPCExternalLocationsAdmin.RemoveExternalLocation

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RemoveExternalLocation/

Badges: `Administration API / specialized` `admin` `session`

Deletes an external location, optionally destroying the documents whose files are linked to it.

- **Service:** [External locations](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/index.md) `MFiles.IRPCExternalLocationsAdmin`
- **gRPC method:** `/MFiles.IRPCExternalLocationsAdmin/RemoveExternalLocation`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/remove-external-location`
- **Request:** [`RemoveExternalLocationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RemoveExternalLocation/index.md#request)
- **Response:** [`RemoveExternalLocationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCExternalLocationsAdmin/RemoveExternalLocation/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- With `destroy_docs_with_linked_files` true, **destroys every document that has a file linked to
  the location** before deleting it. This cannot be undone.
- With it false, the call fails while documents with files linked to the location exist.
- Requires `manage_external_locations`.

<a id="request"></a>

## Request: RemoveExternalLocationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `id` | `int32` | The ID of the external location to remove. |
| `destroy_docs_with_linked_files` | `bool` | True to destroy all documents that contain files linked to the external location being removed. |

<a id="response"></a>

## Response: RemoveExternalLocationResponse

No fields.

---

# Thumbnail administration (IRPCThumbnailsAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/

Discards the thumbnail images stored in a vault.

Provides methods for administering thumbnails.

- **gRPC service:** `MFiles.IRPCThumbnailsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 1
- **Proto file:** [`mfiles/IRPCThumbnailsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCThumbnailsAdmin.proto)

<a id="overview"></a>

## Overview

The service has one method,
[ResetThumbnailImages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/ResetThumbnailImages/index.md), behind the Reset
Thumbnail Images command of a vault in M-Files Admin. It needs a vault session with the vault
rights `change_metadata_structure` and `license_allows_modifications`
([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [ResetThumbnailImages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/ResetThumbnailImages/index.md) | Discards all thumbnail images stored in the vault. | `admin` `session` `idempotent` |

---

# IRPCThumbnailsAdmin.ResetThumbnailImages

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Thumbnail administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/ResetThumbnailImages/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Discards all thumbnail images stored in the vault.

- **Service:** [Thumbnail administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/index.md) `MFiles.IRPCThumbnailsAdmin`
- **gRPC method:** `/MFiles.IRPCThumbnailsAdmin/ResetThumbnailImages`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/reset-thumbnail-images`
- **Request:** [`ResetThumbnailImagesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/ResetThumbnailImages/index.md#request)
- **Response:** [`ResetThumbnailImagesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCThumbnailsAdmin/ResetThumbnailImages/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Deletes the stored thumbnail image of every file in the vault and clears the thumbnail
  information of the files. Files and documents are not changed.
- Requires the vault rights `change_metadata_structure` and `license_allows_modifications`.

<a id="request"></a>

## Request: ResetThumbnailImagesRequest

No fields.

<a id="response"></a>

## Response: ResetThumbnailImagesResponse

No fields.

---

# Web access administration (IRPCWebAccessAdmin)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/

Sets up M-Files Web in Internet Information Services (IIS) on the server computer.

NOTE: Do NOT change the layout of methods and their parameters
so that older clients could utilize this interface against a newer
server.

Before client can use this interface, login is needed to the server.
This can be achieved through the IRPCLogin interface.

- **gRPC service:** `MFiles.IRPCWebAccessAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 7
- **Proto file:** [`mfiles/IRPCWebAccessAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCWebAccessAdmin.proto)

<a id="overview"></a>

## Overview

**For M-Files components only.** M-Files Admin uses this service in its M-Files Web
configuration dialog to check the IIS prerequisites and to create or reuse an IIS web site or
virtual directory for M-Files Web. Applications should not call it.

**Sessions and rights.** Every method requires the system administrator server role (server
right `edit_web_access_settings` in [ServerAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAccess/index.md)); a server-level
session is enough. Other callers get "Access denied. You do not have the server-level access
rights required by this operation.".

Typical order in M-Files Admin:
[CheckCommonRequirements](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirements/index.md) or
[CheckCommonRequirementsForWeb](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirementsForWeb/index.md),
then [QueryADSIObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/QueryADSIObjects/index.md) to list the IIS web
sites, then [UseExistingWebSite](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/UseExistingWebSite/index.md),
[CreateWebSite](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateWebSite/index.md) or
[CreateVirtualDirectory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateVirtualDirectory/index.md).
The IIS objects are addressed with ADSI paths such as `IIS://localhost/w3svc/2/ROOT`.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [CheckCommonRequirements](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirements/index.md) | Checks that IIS and ASP.NET are installed and configured as M-Files Web needs. | `internal: not for applications` `admin` `session` `idempotent` |
| [CheckCommonRequirementsForWeb](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirementsForWeb/index.md) | Checks the IIS prerequisites of the new M-Files Web, including the URL Rewrite and Application Request Routing modules. | `internal: not for applications` `admin` `session` `idempotent` |
| [CreateVirtualDirectory](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateVirtualDirectory/index.md) | Creates an IIS virtual directory for M-Files Web under an existing web site. | `internal: not for applications` `admin` `session` |
| [CreateWebSite](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateWebSite/index.md) | Creates a new IIS web site for M-Files Web. | `internal: not for applications` `admin` `session` |
| [NotifyHttpGrpcService](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/NotifyHttpGrpcService/index.md) | Tells the server's HTTP-to-gRPC gateway that web client settings (such as add-in settings or the default web client) have changed. | `internal: not for applications` `admin` `session` `idempotent` |
| [QueryADSIObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/QueryADSIObjects/index.md) | Lists the child objects of an IIS (ADSI) path on the server computer, for example its web sites. | `internal: not for applications` `admin` `session` `idempotent` |
| [UseExistingWebSite](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/UseExistingWebSite/index.md) | Configures an existing IIS web site for M-Files Web. | `internal: not for applications` `admin` `session` `idempotent` |

---

# IRPCWebAccessAdmin.CheckCommonRequirements

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirements/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Checks that IIS and ASP.NET are installed and configured as M-Files Web needs.

- **Service:** [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `MFiles.IRPCWebAccessAdmin`
- **gRPC method:** `/MFiles.IRPCWebAccessAdmin/CheckCommonRequirements`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-common-requirements`
- **Request:** [`CheckCommonRequirementsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirements/index.md#request)
- **Response:** [`CheckCommonRequirementsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirements/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** Used by M-Files Admin. Applications should not call it.
- Requires the system administrator server role (server right `edit_web_access_settings`).
  Denied for other callers.
- A missing prerequisite fails the call with an error that names it; on success
  `requirements_met` is true.

<a id="request"></a>

## Request: CheckCommonRequirementsRequest

No fields.

<a id="response"></a>

## Response: CheckCommonRequirementsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `requirements_met` | `bool` | True if the requirements are met. When they are not, the call fails with an error that describes the missing requirement. |

<a id="related"></a>

## Related methods

- [CheckCommonRequirementsForWeb](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirementsForWeb/index.md): Checks the IIS prerequisites of the new M-Files Web, including the URL Rewrite and Application Request Routing modules.

---

# IRPCWebAccessAdmin.CheckCommonRequirementsForWeb

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirementsForWeb/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Checks the IIS prerequisites of the new M-Files Web, including the URL Rewrite and Application
Request Routing modules.

- **Service:** [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `MFiles.IRPCWebAccessAdmin`
- **gRPC method:** `/MFiles.IRPCWebAccessAdmin/CheckCommonRequirementsForWeb`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/check-common-requirements-for-web`
- **Request:** [`CheckCommonRequirementsForWebRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirementsForWeb/index.md#request)
- **Response:** [`CheckCommonRequirementsForWebResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirementsForWeb/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** Used by M-Files Admin. Applications should not call it.
- Requires the system administrator server role (server right `edit_web_access_settings`).
- A missing prerequisite fails the call with an error that names it.

<a id="request"></a>

## Request: CheckCommonRequirementsForWebRequest

No fields.

<a id="response"></a>

## Response: CheckCommonRequirementsForWebResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `requirements_met` | `bool` | True if the requirements are met. When they are not, the call fails with an error that describes the missing requirement. |

<a id="related"></a>

## Related methods

- [CheckCommonRequirements](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CheckCommonRequirements/index.md): Checks that IIS and ASP.NET are installed and configured as M-Files Web needs.

---

# IRPCWebAccessAdmin.CreateVirtualDirectory

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateVirtualDirectory/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session`

Creates an IIS virtual directory for M-Files Web under an existing web site.

- **Service:** [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `MFiles.IRPCWebAccessAdmin`
- **gRPC method:** `/MFiles.IRPCWebAccessAdmin/CreateVirtualDirectory`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-virtual-directory`
- **Request:** [`CreateVirtualDirectoryRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateVirtualDirectory/index.md#request)
- **Response:** [`CreateVirtualDirectoryResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateVirtualDirectory/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** Used by M-Files Admin. Applications should not call it.
- Changes the IIS configuration of the server computer. Requires Windows Server; other Windows
  editions fail.
- Requires the system administrator server role (server right `edit_web_access_settings`).

<a id="request"></a>

## Request: CreateVirtualDirectoryRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `ads_path_parent` | `string` | The ADSI path of the parent node, for example `IIS://localhost/w3svc/2/ROOT` for the root of the web site whose ID is 2. |
| `name` | `string` | The name of the virtual directory. |
| `enable_new_web` | `bool` | True to set it up for the new M-Files Web. |

<a id="response"></a>

## Response: CreateVirtualDirectoryResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `virtual_dir` | [`ADSIObject`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ADSIObject/index.md) | The created virtual directory. |
| `virtual_dir.name` | `string` | The name of the object. |
| `virtual_dir.display_name` | `string` | The display name of the object. |
| `virtual_dir.schema_class` | `string` | The name of the object's schema class. |
| `virtual_dir.guid` | `string` | The GUID of the object as stored in the underlying directory store. |
| `virtual_dir.path` | `string` | The object's ADsPath that uniquely identifies this object from all others. |
| `virtual_dir.parent_path` | `string` | The ADsPath string for the parent of the object. |

---

# IRPCWebAccessAdmin.CreateWebSite

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateWebSite/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session`

Creates a new IIS web site for M-Files Web.

- **Service:** [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `MFiles.IRPCWebAccessAdmin`
- **gRPC method:** `/MFiles.IRPCWebAccessAdmin/CreateWebSite`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/create-web-site`
- **Request:** [`CreateWebSiteRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateWebSite/index.md#request)
- **Response:** [`CreateWebSiteResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/CreateWebSite/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** Used by M-Files Admin. Applications should not call it.
- Changes the IIS configuration of the server computer. Requires Windows Server; other Windows
  editions fail.
- Requires the system administrator server role (server right `edit_web_access_settings`).

<a id="request"></a>

## Request: CreateWebSiteRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `name` | `string` | The name of the new web site. |
| `enable_new_web` | `bool` | True to set the site up for the new M-Files Web. |
| `endpoint` | `string` | The port the site listens on, for example `80`. |

<a id="response"></a>

## Response: CreateWebSiteResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `web_site` | [`ADSIObject`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ADSIObject/index.md) | The created web site. |
| `web_site.name` | `string` | The name of the object. |
| `web_site.display_name` | `string` | The display name of the object. |
| `web_site.schema_class` | `string` | The name of the object's schema class. |
| `web_site.guid` | `string` | The GUID of the object as stored in the underlying directory store. |
| `web_site.path` | `string` | The object's ADsPath that uniquely identifies this object from all others. |
| `web_site.parent_path` | `string` | The ADsPath string for the parent of the object. |

---

# IRPCWebAccessAdmin.NotifyHttpGrpcService

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/NotifyHttpGrpcService/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Tells the server's HTTP-to-gRPC gateway that web client settings (such as add-in settings or the
default web client) have changed.

- **Service:** [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `MFiles.IRPCWebAccessAdmin`
- **gRPC method:** `/MFiles.IRPCWebAccessAdmin/NotifyHttpGrpcService`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/notify-http-grpc-service`
- **Request:** [`NotifyHttpGrpcServiceRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/NotifyHttpGrpcService/index.md#request)
- **Response:** [`NotifyHttpGrpcServiceResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/NotifyHttpGrpcService/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** M-Files Admin calls it after saving web settings. Applications
should not call it.
- Requires the system administrator server role (server right `edit_web_access_settings`).
- Only the add-in settings, default web client, default web client (IIS) and classic web URL
  redirection flags trigger a notification; other flags are ignored. Errors in delivering the
  notification are not returned.

<a id="request"></a>

## Request: NotifyHttpGrpcServiceRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `settings_to_notify_http_grpc_service` | [`SettingsToNotifyHttpGrpcService`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SettingsToNotifyHttpGrpcService/index.md) | Which settings changed, as [CLIENTSETTINGFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CLIENTSETTINGFLAGS/index.md). |
| `settings_to_notify_http_grpc_service.client_settings` | [`CLIENTSETTINGFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CLIENTSETTINGFLAGS/index.md) | The client settings flags. |
| `settings_to_notify_http_grpc_service.client_settings.all` | `bool` | Specifies all flags set; Including any future flags. |
| `settings_to_notify_http_grpc_service.client_settings.theme` | `bool` | Theme flag |
| `settings_to_notify_http_grpc_service.client_settings.session_timeout` | `bool` | Client session timeout. |
| `settings_to_notify_http_grpc_service.client_settings.default_web_client` | `bool` | Default Web Client. |
| `settings_to_notify_http_grpc_service.client_settings.add_in_settings` | `bool` | Addin Settings. |
| `settings_to_notify_http_grpc_service.client_settings.default_web_client_iis` | `bool` | Default Web Client for IIS. |
| `settings_to_notify_http_grpc_service.client_settings.web_access_cors` | `bool` | CORS settings of Classic web access. |
| `settings_to_notify_http_grpc_service.client_settings.migrate_classic_web_url` | `bool` | Redirect classic web urls. |
| `settings_to_notify_http_grpc_service.client_settings.migrate_web_link_to_online_web` | `bool` | Migrate web links to online web app (Account layer). |
| `settings_to_notify_http_grpc_service.client_settings.custom_banner` | `bool` | Custom banner flag |
| `settings_to_notify_http_grpc_service.client_settings.idle_session_timeout` | `bool` | Idle session timeout. |

<a id="response"></a>

## Response: NotifyHttpGrpcServiceResponse

No fields.

---

# IRPCWebAccessAdmin.QueryADSIObjects

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/QueryADSIObjects/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Lists the child objects of an IIS (ADSI) path on the server computer, for example its web sites.

- **Service:** [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `MFiles.IRPCWebAccessAdmin`
- **gRPC method:** `/MFiles.IRPCWebAccessAdmin/QueryADSIObjects`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/query-adsiobjects`
- **Request:** [`QueryADSIObjectsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/QueryADSIObjects/index.md#request)
- **Response:** [`QueryADSIObjectsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/QueryADSIObjects/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** M-Files Admin uses it to list the IIS web sites. Applications
should not call it.
- Requires the system administrator server role (server right `edit_web_access_settings`).
- Checks the IIS and ASP.NET prerequisites first and fails if they are missing.

<a id="request"></a>

## Request: QueryADSIObjectsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `key` | `string` | The ADSI path to enumerate, for example `IIS://localhost/w3svc` for the web sites. |
| `schema_class` | `string` | Return only children of this schema class; unset returns all children. |

<a id="response"></a>

## Response: QueryADSIObjectsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `objects[]` | repeated [`ADSIObject`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ADSIObject/index.md) | ADSI objects. |
| `objects[].name` | `string` | The name of the object. |
| `objects[].display_name` | `string` | The display name of the object. |
| `objects[].schema_class` | `string` | The name of the object's schema class. |
| `objects[].guid` | `string` | The GUID of the object as stored in the underlying directory store. |
| `objects[].path` | `string` | The object's ADsPath that uniquely identifies this object from all others. |
| `objects[].parent_path` | `string` | The ADsPath string for the parent of the object. |

---

# IRPCWebAccessAdmin.UseExistingWebSite

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/UseExistingWebSite/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `idempotent`

Configures an existing IIS web site for M-Files Web.

- **Service:** [Web access administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/index.md) `MFiles.IRPCWebAccessAdmin`
- **gRPC method:** `/MFiles.IRPCWebAccessAdmin/UseExistingWebSite`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/use-existing-web-site`
- **Request:** [`UseExistingWebSiteRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/UseExistingWebSite/index.md#request)
- **Response:** [`UseExistingWebSiteResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/UseExistingWebSite/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** Used by M-Files Admin. Applications should not call it.
- Changes the IIS configuration of the server computer.
- Requires the system administrator server role (server right `edit_web_access_settings`).
- With `enable_new_web`, the IIS URL Rewrite and Application Request Routing modules must also be
  installed.

<a id="request"></a>

## Request: UseExistingWebSiteRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `ads_path_web_site` | `string` | The ADSI path of the web site, from [QueryADSIObjects](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCWebAccessAdmin/QueryADSIObjects/index.md). |
| `enable_new_web` | `bool` | True to set the site up for the new M-Files Web. |
| `ads_web_site_name` | `string` | The name of the web site, used with `enable_new_web`. |

<a id="response"></a>

## Response: UseExistingWebSiteResponse

No fields.

---

# License management (IRPCLicenseManagement)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/

Reads and sets the server's license, its usage, and whether licensed features such as OCR or
M-Files Web are available.

Use this interface to set or get license code and serial number.

- **gRPC service:** `MFiles.IRPCLicenseManagement`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 6
- **Proto file:** [`mfiles/IRPCLicenseManagement.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCLicenseManagement.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service on its license page. Applications mostly need only
[DoesLicenseHaveFeature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature/index.md), which any
session can call to find out whether an add-on feature is licensed before offering it.

**Sessions and rights.** A server-level session is enough (log in with `login_data.vault_guid` =
`{00000000-0000-0000-0000-000000000000}`). Reading or changing the license code and reading the
usage require the system administrator server role (server right `manage_licenses` in
[ServerAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ServerAccess/index.md)); other callers get "Access denied. You do not
have the server-level access rights required by this operation.". On servers that license each
vault separately through M-Files Manage, a vault administrator can also read that vault's
license and usage from a vault session.

- **Feature checks**:
  [DoesLicenseHaveFeature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature/index.md)
  (session),
  [DoesLicenseHaveFeatureByVaultDNS](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeatureByVaultDNS/index.md)
  (no session).
- **License code**:
  [GetLicenseCodeAndSerialNumber](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseCodeAndSerialNumber/index.md),
  [SetLicenseCodeAndSerialNumber](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/SetLicenseCodeAndSerialNumber/index.md),
  [RefreshLicenseCode](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/RefreshLicenseCode/index.md).
- **Usage**: [GetLicenseUsage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseUsage/index.md).

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [DoesLicenseHaveFeature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature/index.md) | Tells which of the requested add-on features (OCR, M-Files Web, AI search and so on) the license allows. | `admin` `session` `idempotent` |
| [DoesLicenseHaveFeatureByVaultDNS](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeatureByVaultDNS/index.md) | Tells whether a feature is licensed for the vault that a host name points to, without a session. | `admin` `no session` `idempotent` |
| [GetLicenseCodeAndSerialNumber](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseCodeAndSerialNumber/index.md) | Gets the server's serial number, license code and evaluation state. | `admin` `session` `idempotent` |
| [GetLicenseUsage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseUsage/index.md) | Gets how many named, concurrent and read-only user licenses are in use. | `admin` `session` `idempotent` |
| [RefreshLicenseCode](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/RefreshLicenseCode/index.md) | Asks the server to fetch its license again from M-Files Manage. | `admin` `session` `idempotent` |
| [SetLicenseCodeAndSerialNumber](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/SetLicenseCodeAndSerialNumber/index.md) | Installs a new license for the server. | `admin` `session` `idempotent` |

---

# IRPCLicenseManagement.DoesLicenseHaveFeature

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Tells which of the requested add-on features (OCR, M-Files Web, AI search and so on) the license
allows.

- **Service:** [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md) `MFiles.IRPCLicenseManagement`
- **gRPC method:** `/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/does-license-have-feature`
- **Request:** [`DoesLicenseHaveFeatureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature/index.md#request)
- **Response:** [`DoesLicenseHaveFeatureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Any session can call it, vault or server-level; no rights are needed. Calls without a
  session fail with `UNAUTHENTICATED`.
- In a vault session, the vault's own license is taken into account.
- Set every feature you are interested in, or `all`; the response repeats the requested features
  that are licensed.

<a id="request"></a>

## Request: DoesLicenseHaveFeatureRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `requested_features` | [`LICENSEDPRODUCTFEATURES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LICENSEDPRODUCTFEATURES/index.md) | The features to check. See [LICENSEDPRODUCTFEATURES](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LICENSEDPRODUCTFEATURES/index.md). |
| `requested_features.all` | `bool` | Specifies all flags set; Including any future flags. |
| `requested_features.ocr` | `bool` | OCR. |
| `requested_features.electronic_signatures` | `bool` | 21 CFR Part 11. |
| `requested_features.reporting` | `bool` | Data export and Reporting. |
| `requested_features.ocr_hyper_compression` | `bool` | OCR hyper-compression. |
| `requested_features.intelligent_metadata_layer` | `bool` | Intelligent Metadata Layer. |
| `requested_features.web_user_interface` | `bool` | Web User Interface. |
| `requested_features.embedded_google_gsuite` | `bool` | Google g suite. |
| `requested_features.embedded_share_point` | `bool` | SharePoint Online. |
| `requested_features.embedded_salesforce` | `bool` | Salesforce Online. |
| `requested_features.embedded_arc_gis` | `bool` | Esri ArcGIS. |
| `requested_features.outlook_addin` | `bool` | Outlook Add-in. |
| `requested_features.aino_insights` | `bool` | Aino Usage: Semantic Index. |
| `requested_features.ai_search` | `bool` | AI Search. |

<a id="response"></a>

## Response: DoesLicenseHaveFeatureResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `supported_features` | [`LICENSEDPRODUCTFEATURES`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.LICENSEDPRODUCTFEATURES/index.md) | The requested features that the license allows; the others are false. |
| `supported_features.all` | `bool` | Specifies all flags set; Including any future flags. |
| `supported_features.ocr` | `bool` | OCR. |
| `supported_features.electronic_signatures` | `bool` | 21 CFR Part 11. |
| `supported_features.reporting` | `bool` | Data export and Reporting. |
| `supported_features.ocr_hyper_compression` | `bool` | OCR hyper-compression. |
| `supported_features.intelligent_metadata_layer` | `bool` | Intelligent Metadata Layer. |
| `supported_features.web_user_interface` | `bool` | Web User Interface. |
| `supported_features.embedded_google_gsuite` | `bool` | Google g suite. |
| `supported_features.embedded_share_point` | `bool` | SharePoint Online. |
| `supported_features.embedded_salesforce` | `bool` | Salesforce Online. |
| `supported_features.embedded_arc_gis` | `bool` | Esri ArcGIS. |
| `supported_features.outlook_addin` | `bool` | Outlook Add-in. |
| `supported_features.aino_insights` | `bool` | Aino Usage: Semantic Index. |
| `supported_features.ai_search` | `bool` | AI Search. |

<a id="related"></a>

## Related methods

- [DoesLicenseHaveFeatureByVaultDNS](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeatureByVaultDNS/index.md): Tells whether a feature is licensed for the vault that a host name points to, without a session.

---

# IRPCLicenseManagement.DoesLicenseHaveFeatureByVaultDNS

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeatureByVaultDNS/

Badges: `Administration API / specialized` `admin` `no session` `idempotent`

Tells whether a feature is licensed for the vault that a host name points to, without a session.

- **Service:** [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md) `MFiles.IRPCLicenseManagement`
- **gRPC method:** `/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeatureByVaultDNS`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/does-license-have-feature-by-vault-dns`
- **Request:** [`DoesLicenseHaveFeatureByVaultDNSRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeatureByVaultDNS/index.md#request)
- **Response:** [`DoesLicenseHaveFeatureByVaultDNSResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeatureByVaultDNS/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Not needed: the call can be made before logging in.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Needs no session; works anonymously, also on M-Files Cloud.
- Returns true if the server license has the feature, whatever host name is given. Otherwise,
  on servers that license vaults separately, the host name is looked up in the server's vault
  host name configuration and the vault license is checked.
- An unknown host name or an unsupported feature gives false, not an error.

<a id="request"></a>

## Request: DoesLicenseHaveFeatureByVaultDNSRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `vault_dns_name` | `string` | The host name of the vault, without `https://`. |
| `requested_feature` | [`LicensedProductFeature`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.LicensedProductFeature/index.md) | The feature to check. |

<a id="response"></a>

## Response: DoesLicenseHaveFeatureByVaultDNSResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `is_feature_enabled` | `bool` | True if the feature is licensed. |

<a id="related"></a>

## Related methods

- [DoesLicenseHaveFeature](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/DoesLicenseHaveFeature/index.md): Tells which of the requested add-on features (OCR, M-Files Web, AI search and so on) the license allows.

---

# IRPCLicenseManagement.GetLicenseCodeAndSerialNumber

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseCodeAndSerialNumber/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets the server's serial number, license code and evaluation state.

- **Service:** [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md) `MFiles.IRPCLicenseManagement`
- **gRPC method:** `/MFiles.IRPCLicenseManagement/GetLicenseCodeAndSerialNumber`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-license-code-and-serial-number`
- **Request:** [`GetLicenseCodeAndSerialNumberRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseCodeAndSerialNumber/index.md#request)
- **Response:** [`GetLicenseCodeAndSerialNumberResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseCodeAndSerialNumber/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_licenses`). Denied for a
  vault administrator on a server with a server license.
- On servers that license each vault through M-Files Manage, a vault session of a vault
  administrator gets that vault's license instead; the evaluation fields are then not set.

<a id="request"></a>

## Request: GetLicenseCodeAndSerialNumberRequest

Get server license information request.

No fields.

<a id="response"></a>

## Response: GetLicenseCodeAndSerialNumberResponse

Get server license information response.

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `evaluation_mode` | `bool` | Tells if the server is running in evaluation mode. |
| `evaluation_expired` | `bool` | True if the evaluation period has ended. Valid only when `evaluation_mode` is true. |
| `evaluation_days_left` | `uint32` | Days left in the evaluation period. Valid only when `evaluation_mode` is true and `evaluation_expired` is false. |
| `serial_number` | `string` | The serial number. Empty in evaluation mode. |
| `license_code` | `string` | The license code. Empty in evaluation mode. |
| `last_license_retrieval` | `string` | When the license was last fetched from M-Files Manage, if the server gets its license from there. |

---

# IRPCLicenseManagement.GetLicenseUsage

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseUsage/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Gets how many named, concurrent and read-only user licenses are in use.

- **Service:** [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md) `MFiles.IRPCLicenseManagement`
- **gRPC method:** `/MFiles.IRPCLicenseManagement/GetLicenseUsage`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-license-usage`
- **Request:** [`GetLicenseUsageRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseUsage/index.md#request)
- **Response:** [`GetLicenseUsageResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/GetLicenseUsage/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_licenses`). Denied for a
  vault administrator in a vault session on a server with a server license.
- On servers that license each vault through M-Files Manage, a vault session of a vault
  administrator gets the usage of that vault instead.

<a id="request"></a>

## Request: GetLicenseUsageRequest

No fields.

<a id="response"></a>

## Response: GetLicenseUsageResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `num_of_named_user_licenses_in_use` | `uint32` | Receives the number of named user licenses in use. |
| `num_of_concurrent_user_licenses_in_use` | `uint32` | Receives the number of concurrent user licenses in use. |
| `num_of_named_read_only_user_licenses_in_use` | `uint32` | Receives the number of read-only user licenses in use. |

---

# IRPCLicenseManagement.RefreshLicenseCode

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/RefreshLicenseCode/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Asks the server to fetch its license again from M-Files Manage.

- **Service:** [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md) `MFiles.IRPCLicenseManagement`
- **gRPC method:** `/MFiles.IRPCLicenseManagement/RefreshLicenseCode`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/refresh-license-code`
- **Request:** [`RefreshLicenseCodeRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/RefreshLicenseCode/index.md#request)
- **Response:** [`RefreshLicenseCodeResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/RefreshLicenseCode/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Has an effect only on servers that get their license from M-Files Manage; elsewhere it does
  nothing.
- Requires the system administrator server role (server right `manage_licenses`). On servers
  that get their license from M-Files Manage, a vault administrator can also call it from a
  vault session; then only that vault's license is refreshed.
- In a server-level session, all licenses of the server are refreshed.

<a id="request"></a>

## Request: RefreshLicenseCodeRequest

No fields.

<a id="response"></a>

## Response: RefreshLicenseCodeResponse

No fields.

---

# IRPCLicenseManagement.SetLicenseCodeAndSerialNumber

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/SetLicenseCodeAndSerialNumber/

Badges: `Administration API / specialized` `admin` `session` `idempotent`

Installs a new license for the server.

- **Service:** [License management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/index.md) `MFiles.IRPCLicenseManagement`
- **gRPC method:** `/MFiles.IRPCLicenseManagement/SetLicenseCodeAndSerialNumber`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-license-code-and-serial-number`
- **Request:** [`SetLicenseCodeAndSerialNumberRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/SetLicenseCodeAndSerialNumber/index.md#request)
- **Response:** [`SetLicenseCodeAndSerialNumberResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCLicenseManagement/SetLicenseCodeAndSerialNumber/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** yes
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires the system administrator server role (server right `manage_licenses`).
- The serial number and license code must match each other. All vaults are notified of the new
  license.

<a id="request"></a>

## Request: SetLicenseCodeAndSerialNumberRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `serial_number` | `string` | The serial number of the new license. |
| `license_code` | `string` | The license code that goes with `serial_number`. |

<a id="response"></a>

## Response: SetLicenseCodeAndSerialNumberResponse

No fields.

---

# Monitoring status (IRPCMonitoringStatus)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/

Reads the vault's monitoring indicators; currently the status of the search indexes.

This interface provides access to vault specific monitoring indicators.

- **gRPC service:** `MFiles.IRPCMonitoringStatus`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 3
- **Proto file:** [`mfiles/IRPCMonitoringStatus.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCMonitoringStatus.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service to show the indexing status of a vault (whether indexing or a
rebuild is running, batch times, items processed). The only supported context is
`MONITORING_CONTEXT_INDEXING`; other contexts fail with "Not implemented.".

**Sessions and rights.** Every method requires a vault session with the vault right
`see_all_objects` ([VaultAccess](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.VaultAccess/index.md)); vault administrators have it.
A server-level session fails with "Login required.", a normal user with "Access denied.".

Typical order: list the index sources with
[GetIndicatorSources](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicatorSources/index.md), then read their
values with [GetIndicators](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicators/index.md).
[GetActiveNotifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetActiveNotifications/index.md) gives a
quick summary as flags.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [GetActiveNotifications](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetActiveNotifications/index.md) | Gets the active indexing notifications of the vault, such as "re-indexing required" or "rebuild in progress", combined over all indexes. | `admin` `session` |
| [GetIndicators](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicators/index.md) | Gets the indicator values of the vault's monitoring sources, optionally for one source. | `admin` `session` |
| [GetIndicatorSources](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicatorSources/index.md) | Lists the monitoring sources of the vault, for indexing one source per index and partition. | `admin` `session` |

---

# IRPCMonitoringStatus.GetActiveNotifications

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Monitoring status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetActiveNotifications/

Badges: `Administration API / specialized` `admin` `session`

Gets the active indexing notifications of the vault, such as "re-indexing required" or
"rebuild in progress", combined over all indexes.

- **Service:** [Monitoring status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/index.md) `MFiles.IRPCMonitoringStatus`
- **gRPC method:** `/MFiles.IRPCMonitoringStatus/GetActiveNotifications`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-active-notifications`
- **Request:** [`GetActiveNotificationsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetActiveNotifications/index.md#request)
- **Response:** [`GetActiveNotificationsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetActiveNotifications/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with the vault right `see_all_objects`.
- `context` must be `MONITORING_CONTEXT_INDEXING`; other values fail with "Not implemented.".

<a id="request"></a>

## Request: GetActiveNotificationsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `context` | [`MonitoringContext`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MonitoringContext/index.md) | Set `MONITORING_CONTEXT_INDEXING`. Values: `MONITORING_CONTEXT_UNSPECIFIED` (0), `MONITORING_CONTEXT_INDEXING` (1). |

<a id="response"></a>

## Response: GetActiveNotificationsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `notifications` | `uint32` | The bits of [INDEXNOTIFICATIONFLAGS](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.INDEXNOTIFICATIONFLAGS/index.md) as a number, ORed over all indexes: 1 re-index required (property definitions changed), 2 re-index required (language changed), 4 re-index required, 8 indexing in progress, 16 rebuild in progress, 32 active file data index required, 64 active metadata index required. 0 means no notifications. |

---

# IRPCMonitoringStatus.GetIndicators

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Monitoring status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicators/

Badges: `Administration API / specialized` `admin` `session`

Gets the indicator values of the vault's monitoring sources, optionally for one source.

- **Service:** [Monitoring status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/index.md) `MFiles.IRPCMonitoringStatus`
- **gRPC method:** `/MFiles.IRPCMonitoringStatus/GetIndicators`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-indicators`
- **Request:** [`GetIndicatorsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicators/index.md#request)
- **Response:** [`GetIndicatorsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicators/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with the vault right `see_all_objects`.
- `source_filter.context` must be `MONITORING_CONTEXT_INDEXING`. Descriptors you leave out
  match any value, so a filter with only the context returns all indexes.
- Each indicator is a tagged value with the time it was generated, for example
  `Common.rebuildInProgress` or `Normal.batchCommittedAt`.

<a id="request"></a>

## Request: GetIndicatorsRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `source_filter` | [`MonitoringSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MonitoringSource/index.md) | The context and, optionally, descriptors (as returned by [GetIndicatorSources](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicatorSources/index.md)) that select the sources. |
| `source_filter.context` | [`MonitoringContext`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MonitoringContext/index.md) | The context of the monitoring source. Values: `MONITORING_CONTEXT_UNSPECIFIED` (0), `MONITORING_CONTEXT_INDEXING` (1). |
| `source_filter.descriptors[]` | repeated [`TaggedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TaggedValue/index.md) | The descriptors of the monitoring source as a tagged value array. |
| `source_filter.descriptors[].tag` | `string` | The name of the tagged value. |
| `source_filter.descriptors[].value_type` | [`TaggedValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.TaggedValueType/index.md) | The value type of the tagged value. Values: `TAGGED_VALUE_TYPE_DEFAULT` (0), `TAGGED_VALUE_TYPE_STRING` (1), `TAGGED_VALUE_TYPE_INTEGER` (2), `TAGGED_VALUE_TYPE_FLOAT` (3), `TAGGED_VALUE_TYPE_BOOLEAN` (4), `TAGGED_VALUE_TYPE_DATETIME` (5), `TAGGED_VALUE_TYPE_INT64` (6). |
| `source_filter.descriptors[].value` | `string` | The string representation of the tagged value. |

<a id="response"></a>

## Response: GetIndicatorsResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `data[]` | repeated [`MonitoringIndicatorData`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MonitoringIndicatorData/index.md) | One entry per source, with its indicators. |
| `data[].source` | [`MonitoringSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MonitoringSource/index.md) | Indicator data source. |
| `data[].source.context` | [`MonitoringContext`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MonitoringContext/index.md) | The context of the monitoring source. Values: `MONITORING_CONTEXT_UNSPECIFIED` (0), `MONITORING_CONTEXT_INDEXING` (1). |
| `data[].source.descriptors[]` | repeated [`TaggedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TaggedValue/index.md) | The descriptors of the monitoring source as a tagged value array. |
| `data[].indicators[]` | repeated [`MonitoringIndicator`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MonitoringIndicator/index.md) | Indicator data as a monitoring indicator array. |
| `data[].indicators[].value` | [`TaggedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TaggedValue/index.md) | The indicator value. |
| `data[].indicators[].generated_at` | `string` | The ISO 8601 timestamp (in UTC) of the indicator value generation. |

---

# IRPCMonitoringStatus.GetIndicatorSources

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Monitoring status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicatorSources/

Badges: `Administration API / specialized` `admin` `session`

Lists the monitoring sources of the vault, for indexing one source per index and partition.

- **Service:** [Monitoring status](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/index.md) `MFiles.IRPCMonitoringStatus`
- **gRPC method:** `/MFiles.IRPCMonitoringStatus/GetIndicatorSources`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-indicator-sources`
- **Request:** [`GetIndicatorSourcesRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicatorSources/index.md#request)
- **Response:** [`GetIndicatorSourcesResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicatorSources/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Requires a vault session with the vault right `see_all_objects`.
- `context` must be `MONITORING_CONTEXT_INDEXING`; unset fails with "Not implemented.".
- Each source is described by tagged values; for indexing the tags are `index`, `shared`,
  `auxiliaryIndexID` and `partition`.

<a id="request"></a>

## Request: GetIndicatorSourcesRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `context` | [`MonitoringContext`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MonitoringContext/index.md) | Set `MONITORING_CONTEXT_INDEXING`. Values: `MONITORING_CONTEXT_UNSPECIFIED` (0), `MONITORING_CONTEXT_INDEXING` (1). |

<a id="response"></a>

## Response: GetIndicatorSourcesResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `sources[]` | repeated [`MonitoringSource`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MonitoringSource/index.md) | The sources. Pass one as `source_filter` to [GetIndicators](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCMonitoringStatus/GetIndicators/index.md). |
| `sources[].context` | [`MonitoringContext`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MonitoringContext/index.md) | The context of the monitoring source. Values: `MONITORING_CONTEXT_UNSPECIFIED` (0), `MONITORING_CONTEXT_INDEXING` (1). |
| `sources[].descriptors[]` | repeated [`TaggedValue`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.TaggedValue/index.md) | The descriptors of the monitoring source as a tagged value array. |
| `sources[].descriptors[].tag` | `string` | The name of the tagged value. |
| `sources[].descriptors[].value_type` | [`TaggedValueType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.TaggedValueType/index.md) | The value type of the tagged value. Values: `TAGGED_VALUE_TYPE_DEFAULT` (0), `TAGGED_VALUE_TYPE_STRING` (1), `TAGGED_VALUE_TYPE_INTEGER` (2), `TAGGED_VALUE_TYPE_FLOAT` (3), `TAGGED_VALUE_TYPE_BOOLEAN` (4), `TAGGED_VALUE_TYPE_DATETIME` (5), `TAGGED_VALUE_TYPE_INT64` (6). |
| `sources[].descriptors[].value` | `string` | The string representation of the tagged value. |

---

# Declarative metadata structure (IRPCDeclarativeMetadataStructure)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/

Reads and validates the whole metadata structure of a vault as one declarative JSON document.
Preview feature, off by default.

- **gRPC service:** `MFiles.IRPCDeclarativeMetadataStructure`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 8
- **Proto file:** [`mfiles/IRPCDeclarativeMetadataStructure.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCDeclarativeMetadataStructure.proto)

<a id="overview"></a>

## Overview

**Not available by default.** The declarative metadata structure is a preview feature. On a
server where it is not enabled, every method fails with "Not implemented." (gRPC status
`UNKNOWN`, error code 0x80004001) before any rights check.
[SetDeclarativeMetadataStructureBeginSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/index.md),
[SetDeclarativeMetadataStructureEndSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/index.md)
and
[NewDeclarativeMetadataStructureRevisionAvailable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable/index.md)
are not implemented even when the feature is on.

**The declarative format.** A declarative metadata structure document is a JSON text that
describes the vault's object types, value lists, classes, class groups, property definitions,
workflows and named access control lists, with the users, user groups and value list items they
refer to. Elements refer to each other **by name**, not by vault-specific ID, so the document can
be read, compared and edited by people and tools. Property names are camelCase and enumerations
are strings. The document also carries `schemaVersion`, `writerInfo`, and the structure's
`revision` (positive: a revision from the declarative configuration service; negative: a
revision made locally on this server, with `revisionBase` naming the revision it is based on).
[GenerateDeclarativeMetadataStructureSchema](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/index.md)
returns the JSON Schema of the format.

**How the two services relate.**
[IRPCDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md)
exchanges the same structure as a typed
[DeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DeclarativeMetadataStructure/index.md) message that uses the
vault's IDs. This service exchanges the declarative JSON document as a string. The server
converts between the two with the declarative configuration converter that is installed with
M-Files Server:
[GetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/index.md)
builds the typed structure and converts it to JSON;
[SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md)
validates or converts JSON in the other direction.

- **Session and rights.** Every method requires a vault session and the vault right
  `change_metadata_structure`, reads included.
- **Who calls it.** Declarative configuration tooling for M-Files. Applications should read the
  structure with the Vault API ([IRPCObjectTypes](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCObjectTypes/index.md),
  [IRPCPropertyDefs](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCPropertyDefs/index.md)) and should not call this service.
- **Revision generation.** When this feature is on, every local structure change makes the server
  generate a new revision of the declarative structure.
  [PauseDeclarativeMetadataStructureRevisionGeneration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration/index.md)
  lets one session make a batch of changes with one catch-up revision at the end.
- Every method sends the `mfiles-metadata-version-bin` trailer when it succeeds.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [CancelDeclarativeMetadataStructureRevisionGenerationPause](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause/index.md) | Ends the calling session's pause of automatic revision generation. | `admin` `session` `returns metadata structure version` |
| [GenerateDeclarativeMetadataStructureSchema](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/index.md) | Gets the JSON Schema document that describes the declarative metadata structure format. | `admin` `session` `returns metadata structure version` |
| [GetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/index.md) | Gets the vault's current metadata structure as a declarative JSON document. | `admin` `session` `returns metadata structure version` |
| [NewDeclarativeMetadataStructureRevisionAvailable](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable/index.md) | Reserved for telling the server that a new structure revision is available. Not implemented. | `admin` `session` `returns metadata structure version` |
| [PauseDeclarativeMetadataStructureRevisionGeneration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration/index.md) | Starts, extends or reads a pause of automatic revision generation for the calling session. | `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md) | Validates a declarative JSON document against the schema, or converts it for deployment. | `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructureBeginSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/index.md) | Reserved for setting a structure in several parts. Not implemented. | `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructureEndSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/index.md) | Reserved for setting a structure in several parts. Not implemented. | `admin` `session` `returns metadata structure version` |

---

# IRPCDeclarativeMetadataStructure.CancelDeclarativeMetadataStructureRevisionGenerationPause

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Ends the calling session's pause of automatic revision generation.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/cancel-declarative-metadata-structure-revision-generation-pause`
- **Request:** [`CancelDeclarativeMetadataStructureRevisionGenerationPauseRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause/index.md#request)
- **Response:** [`CancelDeclarativeMetadataStructureRevisionGenerationPauseResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Fails with "Not implemented." unless local revision generation is enabled on the server.
- Requires `change_metadata_structure`.
- Ending an active pause makes the server generate the catch-up revision if one is needed.
- Succeeds without effect when the session has no active pause.

<a id="request"></a>

## Request: CancelDeclarativeMetadataStructureRevisionGenerationPauseRequest

No fields.

<a id="response"></a>

## Response: CancelDeclarativeMetadataStructureRevisionGenerationPauseResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `remaining_seconds` | `int32` | Seconds left on this session's pause after the call; normally 0. |

---

# IRPCDeclarativeMetadataStructure.GenerateDeclarativeMetadataStructureSchema

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Gets the JSON Schema document that describes the declarative metadata structure format.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/generate-declarative-metadata-structure-schema`
- **Request:** [`GenerateDeclarativeMetadataStructureSchemaRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/index.md#request)
- **Response:** [`GenerateDeclarativeMetadataStructureSchemaResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Fails with "Not implemented." unless the feature is enabled on the server.
- Requires `change_metadata_structure`. Changes nothing.
- Validate a document against this schema locally, or on the server with
  [SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md)
  and `dry_run_with_schema_validation`.

<a id="request"></a>

## Request: GenerateDeclarativeMetadataStructureSchemaRequest

No fields.

<a id="response"></a>

## Response: GenerateDeclarativeMetadataStructureSchemaResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `declmds_schema` | `string` | The JSON Schema of the declarative metadata structure document, as text. |

<a id="related"></a>

## Related methods

- [SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md): Validates a declarative JSON document against the schema, or converts it for deployment.

---

# IRPCDeclarativeMetadataStructure.GetDeclarativeMetadataStructure

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Gets the vault's current metadata structure as a declarative JSON document.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-declarative-metadata-structure`
- **Request:** [`GetDeclarativeMetadataStructureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/index.md#request)
- **Response:** [`GetDeclarativeMetadataStructureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Fails with "Not implemented." unless the feature is enabled on the server.
- Requires `change_metadata_structure`.
- Always returns the current structure: the server does not read `revision`.
- The conversion runs in a separate converter process on the server, with a one-minute limit.

<a id="request"></a>

## Request: GetDeclarativeMetadataStructureRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `revision` | `int32` | Not used by the server; the current structure is returned. |

<a id="response"></a>

## Response: GetDeclarativeMetadataStructureResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `declmds` | `string` | The declarative metadata structure document (JSON text). Its format is described by [GenerateDeclarativeMetadataStructureSchema](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GenerateDeclarativeMetadataStructureSchema/index.md). |

---

# IRPCDeclarativeMetadataStructure.NewDeclarativeMetadataStructureRevisionAvailable

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Reserved for telling the server that a new structure revision is available. Not implemented.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/new-declarative-metadata-structure-revision-available`
- **Request:** [`NewDeclarativeMetadataStructureRevisionAvailableRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable/index.md#request)
- **Response:** [`NewDeclarativeMetadataStructureRevisionAvailableResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/NewDeclarativeMetadataStructureRevisionAvailable/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Always fails with "Not implemented.", whether or not the feature is enabled.

<a id="request"></a>

## Request: NewDeclarativeMetadataStructureRevisionAvailableRequest

No fields.

<a id="response"></a>

## Response: NewDeclarativeMetadataStructureRevisionAvailableResponse

No fields.

---

# IRPCDeclarativeMetadataStructure.PauseDeclarativeMetadataStructureRevisionGeneration

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Starts, extends or reads a pause of automatic revision generation for the calling session.

While the pause is active, structure changes made by this session do not each generate a new
revision of the declarative metadata structure. When the pause ends, by
[CancelDeclarativeMetadataStructureRevisionGenerationPause](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause/index.md)
or by expiry, the server generates one catch-up revision.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/pause-declarative-metadata-structure-revision-generation`
- **Request:** [`PauseDeclarativeMetadataStructureRevisionGenerationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration/index.md#request)
- **Response:** [`PauseDeclarativeMetadataStructureRevisionGenerationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/PauseDeclarativeMetadataStructureRevisionGeneration/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Fails with "Not implemented." unless local revision generation is enabled on the server.
- Requires `change_metadata_structure`.
- A positive `duration_seconds` starts a pause, or extends this session's pause (never shortens
  it). 0 only reads the remaining time and changes nothing. A negative value or more than 3600
  fails with an invalid-argument error.
- Each session has at most one pause, identified by the session itself; other sessions are not
  affected.

<a id="request"></a>

## Request: PauseDeclarativeMetadataStructureRevisionGenerationRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `duration_seconds` | `int32` | The pause length in seconds, 1 to 3600, or 0 to read the status only. |

<a id="response"></a>

## Response: PauseDeclarativeMetadataStructureRevisionGenerationResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `remaining_seconds` | `int32` | Seconds left on this session's pause, rounded up. 0 means no active pause. |

<a id="related"></a>

## Related methods

- [CancelDeclarativeMetadataStructureRevisionGenerationPause](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/CancelDeclarativeMetadataStructureRevisionGenerationPause/index.md): Ends the calling session's pause of automatic revision generation.

---

# IRPCDeclarativeMetadataStructure.SetDeclarativeMetadataStructure

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Validates a declarative JSON document against the schema, or converts it for deployment.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-declarative-metadata-structure`
- **Request:** [`SetDeclarativeMetadataStructureRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md#request)
- **Response:** [`SetDeclarativeMetadataStructureResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Fails with "Not implemented." unless deploying declarative structures is enabled on the server.
- Requires `change_metadata_structure`.
- With `dry_run_with_schema_validation` true, nothing changes: `validated` is true and
  `validation_errors` lists the schema violations (empty when the document is valid).
- With `dry_run_with_schema_validation` false, the server converts the document but, in this
  server version, does not apply the result to the vault.
- `session` is not used; the begin and end session methods are not implemented.

<a id="request"></a>

## Request: SetDeclarativeMetadataStructureRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `session` | `uint32` | Not used by the server. Leave 0. |
| `declmds_as_json` | `string` | The declarative metadata structure document, as returned by [GetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/GetDeclarativeMetadataStructure/index.md). |
| `dry_run_with_schema_validation` | `bool` | True to only validate the document against the schema. |

<a id="response"></a>

## Response: SetDeclarativeMetadataStructureResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `validated` | `bool` | True when the call was a dry run. |
| `validation_errors` | `string` | The schema validation errors as text, empty if the document is valid. Set only when `validated` is true. |

<a id="related"></a>

## Related methods

- [SetDeclarativeMetadataStructureBeginSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/index.md): Reserved for setting a structure in several parts. Not implemented.
- [SetDeclarativeMetadataStructureEndSession](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/index.md): Reserved for setting a structure in several parts. Not implemented.

---

# IRPCDeclarativeMetadataStructure.SetDeclarativeMetadataStructureBeginSession

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Reserved for setting a structure in several parts. Not implemented.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-declarative-metadata-structure-begin-session`
- **Request:** [`SetDeclarativeMetadataStructureBeginSessionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/index.md#request)
- **Response:** [`SetDeclarativeMetadataStructureBeginSessionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureBeginSession/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Always fails with "Not implemented.", whether or not the feature is enabled.

<a id="request"></a>

## Request: SetDeclarativeMetadataStructureBeginSessionRequest

No fields.

<a id="response"></a>

## Response: SetDeclarativeMetadataStructureBeginSessionResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `session` | `uint32` | Session identifier. |

<a id="related"></a>

## Related methods

- [SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md): Validates a declarative JSON document against the schema, or converts it for deployment.

---

# IRPCDeclarativeMetadataStructure.SetDeclarativeMetadataStructureEndSession

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/

Badges: `Administration API / specialized` `admin` `session` `returns metadata structure version`

Reserved for setting a structure in several parts. Not implemented.

- **Service:** [Declarative metadata structure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md) `MFiles.IRPCDeclarativeMetadataStructure`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-declarative-metadata-structure-end-session`
- **Request:** [`SetDeclarativeMetadataStructureEndSessionRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/index.md#request)
- **Response:** [`SetDeclarativeMetadataStructureEndSessionResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructureEndSession/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Always fails with "Not implemented.", whether or not the feature is enabled.

<a id="request"></a>

## Request: SetDeclarativeMetadataStructureEndSessionRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `session` | `uint32` | Session identifier. |
| `commit` | `bool` | True to commit the Set operation. |
| `dry_run_with_schema_validation` | `bool` | Reserved. Ignored when `commit` is false. |

<a id="response"></a>

## Response: SetDeclarativeMetadataStructureEndSessionResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `validated` | `bool` | True for dry runs with schema validation. |
| `validation_errors` | `string` | Reserved. Set only when `validated` is true. |

<a id="related"></a>

## Related methods

- [SetDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/SetDeclarativeMetadataStructure/index.md): Validates a declarative JSON document against the schema, or converts it for deployment.

---

# Declarative metadata structure (protobuf) (IRPCDeclarativeMetadataStructureAsProtobuf)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/

Reads and replaces the whole metadata structure of a vault as one typed message. Preview feature,
off by default; for the declarative configuration converter.

- **gRPC service:** `MFiles.IRPCDeclarativeMetadataStructureAsProtobuf`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 4
- **Proto file:** [`mfiles/IRPCDeclarativeMetadataStructureAsProtobuf.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCDeclarativeMetadataStructureAsProtobuf.proto)

<a id="overview"></a>

## Overview

**For M-Files components only.** It is meant for the declarative configuration converter that
is installed with M-Files Server, which reads and deploys the vault's structure through it.
Applications should not call it.

- **Not available by default.** On a server where the declarative metadata structure feature is
  not enabled, every method fails with "Not implemented." (gRPC status `UNKNOWN`, error code
  0x80004001) before any rights check.
  [SetDeclarativeMetadataStructureBeginSessionAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureBeginSessionAsProtobuf/index.md)
  and
  [SetDeclarativeMetadataStructureEndSessionAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureEndSessionAsProtobuf/index.md)
  are not implemented even when it is on.
- **Relation to the JSON service.** This service exchanges the structure as a
  [DeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DeclarativeMetadataStructure/index.md) message that uses the
  vault's IDs. [IRPCDeclarativeMetadataStructure](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructure/index.md)
  exchanges the same structure as a declarative JSON document in which elements refer to each
  other by name; the server converts between the two forms. See that service for the format.
- **Session and rights.** Every method requires a vault session and the vault right
  `change_metadata_structure`, reads included.
- Every method sends the `mfiles-metadata-version-bin` trailer when it succeeds.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [GetDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/GetDeclarativeMetadataStructureAsProtobuf/index.md) | Gets the vault's current metadata structure as one typed message. | `internal: not for applications` `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureAsProtobuf/index.md) | Replaces the vault's metadata structure with the given structure. | `internal: not for applications` `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructureBeginSessionAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureBeginSessionAsProtobuf/index.md) | Reserved for setting a structure in several parts. Not implemented. | `internal: not for applications` `admin` `session` `returns metadata structure version` |
| [SetDeclarativeMetadataStructureEndSessionAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureEndSessionAsProtobuf/index.md) | Reserved for setting a structure in several parts. Not implemented. | `internal: not for applications` `admin` `session` `returns metadata structure version` |

---

# IRPCDeclarativeMetadataStructureAsProtobuf.GetDeclarativeMetadataStructureAsProtobuf

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/GetDeclarativeMetadataStructureAsProtobuf/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `returns metadata structure version`

Gets the vault's current metadata structure as one typed message.

- **Service:** [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md) `MFiles.IRPCDeclarativeMetadataStructureAsProtobuf`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/GetDeclarativeMetadataStructureAsProtobuf`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-declarative-metadata-structure-as-protobuf`
- **Request:** [`GetDeclarativeMetadataStructureAsProtobufRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/GetDeclarativeMetadataStructureAsProtobuf/index.md#request)
- **Response:** [`GetDeclarativeMetadataStructureAsProtobufResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/GetDeclarativeMetadataStructureAsProtobuf/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Fails with "Not implemented." unless the feature is enabled on the server.
- Requires `change_metadata_structure`.
- Always returns the current structure: the server does not read `revision`.
- `mds.revision` is the revision to send back with
  [SetDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureAsProtobuf/index.md).

<a id="request"></a>

## Request: GetDeclarativeMetadataStructureAsProtobufRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `revision` | `int32` | Not used by the server; the current structure is returned. |

<a id="response"></a>

## Response: GetDeclarativeMetadataStructureAsProtobufResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `mds` | [`DeclarativeMetadataStructure`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DeclarativeMetadataStructure/index.md) | The complete metadata structure. |
| `mds.revision` | `int32` | Base revision. This is meaningful only if Revision is negative, indicating that the metadata structure is based on a local MFServer revision. In that case, this property indicates the actual revision that the local revision is based on. It may also be zero, which means that there has not been any actual revision deployed to MFServer, and the local revision is based on the initial state of MFServer before any revisions have been deployed. |
| `mds.revision_base` | `int32` | Actual revision-based metadata structure. |
| `mds.object_types[]` | repeated [`ObjectTypeDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeDecl/index.md) | An array of the ObjectTypeDecl structures. |
| `mds.object_types[].ot_admin` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | Object type admin data. |
| `mds.object_types[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The icon resource reference. |
| `mds.object_types[].secrets[]` | repeated [`MetadataStructureSecretRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureSecretRef/index.md) | Per-language translations. |
| `mds.object_types[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.object_types[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.value_lists[]` | repeated [`ObjectTypeDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeDecl/index.md) | An array of the ObjectTypeDecl structures. |
| `mds.value_lists[].ot_admin` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | Object type admin data. |
| `mds.value_lists[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The icon resource reference. |
| `mds.value_lists[].secrets[]` | repeated [`MetadataStructureSecretRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureSecretRef/index.md) | Per-language translations. |
| `mds.value_lists[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.value_lists[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.classes[]` | repeated [`ObjectClassDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClassDecl/index.md) | An array of the ObjectClassDecl structures. |
| `mds.classes[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.classes[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.classes[].object_type` | `int32` | The object type with which this class is used. |
| `mds.classes[].is_predefined` | `bool` | True if this is a predefined class (cannot be deleted, editing is restricted). |
| `mds.classes[].associated_property_defs[]` | repeated [`AssociatedPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) | PropertyDefs associated with this class. |
| `mds.classes[].name_property_def` | `int32` | The ID of the property definition that represents the name of the document or other object. Typically PROPERTYDEF_TITLE (0). |
| `mds.classes[].default_workflow` | `int32` | The default workflow of the document class, or zero if there is no default workflow. |
| `mds.classes[].force_workflow` | `bool` | True if the use of the specified workflow is forced. |
| `mds.classes[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this class. Also specifies who can attach objects to this class. |
| `mds.classes[].signature_settings_for_new_objects` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | The electronic signature settings for creating an electronic signature for new objects. Reserved for future improvements. |
| `mds.classes[].assignment_class_info` | [`AssignmentClassInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssignmentClassInfo/index.md) | Assignment class info. |
| `mds.classes[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.class_groups[]` | repeated [`ObjectClassGroupDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClassGroupDecl/index.md) | An array of the ObjectClassGroupDecl structures. |
| `mds.class_groups[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.class_groups[].object_class_group` | [`ClassGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) | Other information on the class group. |
| `mds.class_groups[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.class_groups[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this class. Also specifies who can attach objects to this class. |
| `mds.class_groups[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.property_defs[]` | repeated [`PropertyDefDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefDecl/index.md) | An array of the PropertyDefDecl structures. |
| `mds.property_defs[].pd_admin` | [`PropertyDefAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) | Property definition admin data. |
| `mds.property_defs[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | Per-language translations. |
| `mds.property_defs[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.property_defs[].automatic_numbering_code` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The automatic numbering VBScript resource reference. |
| `mds.property_defs[].calc_with_vbscript` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The calculated-value VBScript resource reference. |
| `mds.property_defs[].validation_code` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The validation VBScript resource reference. |
| `mds.property_defs[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.workflows[]` | repeated [`WorkflowDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowDecl/index.md) | An array of the WorkflowDecl structures. |
| `mds.workflows[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.workflows[].workflow` | [`WorkflowAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) | Other information on the workflow. |
| `mds.workflows[].states[]` | repeated [`StateDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateDecl/index.md) | The states of this workflow. |
| `mds.workflows[].transitions[]` | repeated [`StateTransitionDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionDecl/index.md) | The state transitions of this workflow. |
| `mds.workflows[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.named_acls[]` | repeated [`NamedAclDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedAclDecl/index.md) | Users and UserGroups as references. |
| `mds.named_acls[].nacl_admin` | [`NamedACLAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md) | Per-language translations. |
| `mds.named_acls[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.named_acls[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.user_accounts[]` | repeated [`UserAccountDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccountDecl/index.md) | An array of the UserAccount structures. |
| `mds.user_accounts[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.user_accounts[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.user_accounts[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `mds.user_accounts[].login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `mds.user_groups[]` | repeated [`UserGroupDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupDecl/index.md) | Value list items as references. |
| `mds.user_groups[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.user_groups[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.user_groups[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `mds.user_groups[].external_name` | `string` | The name for external group. Empty if the group is not external. |
| `mds.value_list_items[]` | repeated [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Named references for all the above elements. |
| `mds.value_list_items[].vlitem` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | Value list item. |
| `mds.value_list_items[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The icon of the item. |
| `mds.value_list_items[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.named_references[]` | repeated [`MetadataStructureNamedReference`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureNamedReference/index.md) | Vault languages. The entry with pwszLanguageCode="" is the default language. |
| `mds.named_references[].reference_type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The structure element type. |
| `mds.named_references[].name` | `string` | The name part of the named reference. |
| `mds.named_references[].element_id` | `int32` | The internal ID of the structure element. |
| `mds.named_references[].type_id` | `int32` | The internal ID of the structure element type. Relevant for MetadataStructureItem::valueListItem only, otherwise ignored. |
| `mds.languages[]` | repeated [`Language`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Language/index.md) | An array of the Language structures defining the vault languages. |
| `mds.languages[].id` | `int32` | Language ID. |
| `mds.languages[].name` | `string` | The name of the language. |
| `mds.languages[].language_code` | `string` | Language indentifier, e.g. the ISO 639-1 or ISO 639-2 language code such as "en" or "eng". |
| `mds.unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped top-level properties, keyed by original property name. |
| `mdver` | `int32` | The vault's metadata structure version that the structure belongs to. |
| `writer_info` | `string` | The server that produced the structure, as `M-Files.<version>`. |

<a id="related"></a>

## Related methods

- [SetDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureAsProtobuf/index.md): Replaces the vault's metadata structure with the given structure.

---

# IRPCDeclarativeMetadataStructureAsProtobuf.SetDeclarativeMetadataStructureAsProtobuf

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureAsProtobuf/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `returns metadata structure version`

Replaces the vault's metadata structure with the given structure.

- **Service:** [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md) `MFiles.IRPCDeclarativeMetadataStructureAsProtobuf`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureAsProtobuf`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-declarative-metadata-structure-as-protobuf`
- **Request:** [`SetDeclarativeMetadataStructureAsProtobufRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureAsProtobuf/index.md#request)
- **Response:** [`SetDeclarativeMetadataStructureAsProtobufResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureAsProtobuf/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Fails with "Not implemented." unless deploying declarative structures is enabled on the server.
- Requires `change_metadata_structure`.
- `mds.revision` must be the vault's current revision, as returned by
  [GetDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/GetDeclarativeMetadataStructureAsProtobuf/index.md);
  otherwise the call fails. Failures are reported as "Setting the declarative metadata structure
  failed." without further detail.

<a id="request"></a>

## Request: SetDeclarativeMetadataStructureAsProtobufRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `session` | `uint32` | Not used by the server. Leave 0. |
| `mds` | [`DeclarativeMetadataStructure`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.DeclarativeMetadataStructure/index.md) | The complete new metadata structure. |
| `mds.revision` | `int32` | Base revision. This is meaningful only if Revision is negative, indicating that the metadata structure is based on a local MFServer revision. In that case, this property indicates the actual revision that the local revision is based on. It may also be zero, which means that there has not been any actual revision deployed to MFServer, and the local revision is based on the initial state of MFServer before any revisions have been deployed. |
| `mds.revision_base` | `int32` | Actual revision-based metadata structure. |
| `mds.object_types[]` | repeated [`ObjectTypeDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeDecl/index.md) | An array of the ObjectTypeDecl structures. |
| `mds.object_types[].ot_admin` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | Object type admin data. |
| `mds.object_types[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The icon resource reference. |
| `mds.object_types[].secrets[]` | repeated [`MetadataStructureSecretRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureSecretRef/index.md) | Per-language translations. |
| `mds.object_types[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.object_types[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.value_lists[]` | repeated [`ObjectTypeDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectTypeDecl/index.md) | An array of the ObjectTypeDecl structures. |
| `mds.value_lists[].ot_admin` | [`ValueListAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListAdmin/index.md) | Object type admin data. |
| `mds.value_lists[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The icon resource reference. |
| `mds.value_lists[].secrets[]` | repeated [`MetadataStructureSecretRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureSecretRef/index.md) | Per-language translations. |
| `mds.value_lists[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.value_lists[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.classes[]` | repeated [`ObjectClassDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClassDecl/index.md) | An array of the ObjectClassDecl structures. |
| `mds.classes[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.classes[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.classes[].object_type` | `int32` | The object type with which this class is used. |
| `mds.classes[].is_predefined` | `bool` | True if this is a predefined class (cannot be deleted, editing is restricted). |
| `mds.classes[].associated_property_defs[]` | repeated [`AssociatedPropertyDef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssociatedPropertyDef/index.md) | PropertyDefs associated with this class. |
| `mds.classes[].name_property_def` | `int32` | The ID of the property definition that represents the name of the document or other object. Typically PROPERTYDEF_TITLE (0). |
| `mds.classes[].default_workflow` | `int32` | The default workflow of the document class, or zero if there is no default workflow. |
| `mds.classes[].force_workflow` | `bool` | True if the use of the specified workflow is forced. |
| `mds.classes[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this class. Also specifies who can attach objects to this class. |
| `mds.classes[].signature_settings_for_new_objects` | [`ElectronicSignatureSettings`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElectronicSignatureSettings/index.md) | The electronic signature settings for creating an electronic signature for new objects. Reserved for future improvements. |
| `mds.classes[].assignment_class_info` | [`AssignmentClassInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AssignmentClassInfo/index.md) | Assignment class info. |
| `mds.classes[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.class_groups[]` | repeated [`ObjectClassGroupDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ObjectClassGroupDecl/index.md) | An array of the ObjectClassGroupDecl structures. |
| `mds.class_groups[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.class_groups[].object_class_group` | [`ClassGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ClassGroup/index.md) | Other information on the class group. |
| `mds.class_groups[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.class_groups[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Specifies the ACL that defines the visibility and other permission settings of this class. Also specifies who can attach objects to this class. |
| `mds.class_groups[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.property_defs[]` | repeated [`PropertyDefDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefDecl/index.md) | An array of the PropertyDefDecl structures. |
| `mds.property_defs[].pd_admin` | [`PropertyDefAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.PropertyDefAdmin/index.md) | Property definition admin data. |
| `mds.property_defs[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | Per-language translations. |
| `mds.property_defs[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.property_defs[].automatic_numbering_code` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The automatic numbering VBScript resource reference. |
| `mds.property_defs[].calc_with_vbscript` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The calculated-value VBScript resource reference. |
| `mds.property_defs[].validation_code` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The validation VBScript resource reference. |
| `mds.property_defs[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.workflows[]` | repeated [`WorkflowDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowDecl/index.md) | An array of the WorkflowDecl structures. |
| `mds.workflows[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.workflows[].workflow` | [`WorkflowAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.WorkflowAdmin/index.md) | Other information on the workflow. |
| `mds.workflows[].states[]` | repeated [`StateDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateDecl/index.md) | The states of this workflow. |
| `mds.workflows[].transitions[]` | repeated [`StateTransitionDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StateTransitionDecl/index.md) | The state transitions of this workflow. |
| `mds.workflows[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.named_acls[]` | repeated [`NamedAclDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedAclDecl/index.md) | Users and UserGroups as references. |
| `mds.named_acls[].nacl_admin` | [`NamedACLAdmin`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.NamedACLAdmin/index.md) | Per-language translations. |
| `mds.named_acls[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.named_acls[].unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped properties for this element, keyed by original property name. |
| `mds.user_accounts[]` | repeated [`UserAccountDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserAccountDecl/index.md) | An array of the UserAccount structures. |
| `mds.user_accounts[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.user_accounts[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.user_accounts[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `mds.user_accounts[].login_name` | `string` | The login name that is associated with this user account (e.g. 'DOMAIN\user'). |
| `mds.user_groups[]` | repeated [`UserGroupDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.UserGroupDecl/index.md) | Value list items as references. |
| `mds.user_groups[].base_info` | [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Value list item representing this element. |
| `mds.user_groups[].aliases` | `string` | Semicolon-separated list of semantic aliases. |
| `mds.user_groups[].acl` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | Permissions. |
| `mds.user_groups[].external_name` | `string` | The name for external group. Empty if the group is not external. |
| `mds.value_list_items[]` | repeated [`ValueListItemDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItemDecl/index.md) | Named references for all the above elements. |
| `mds.value_list_items[].vlitem` | [`ValueListItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ValueListItem/index.md) | Value list item. |
| `mds.value_list_items[].icon` | [`MetadataStructureResourceRef`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureResourceRef/index.md) | The icon of the item. |
| `mds.value_list_items[].translations[]` | repeated [`ElementTranslationsDecl`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ElementTranslationsDecl/index.md) | Per-language translations. |
| `mds.named_references[]` | repeated [`MetadataStructureNamedReference`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureNamedReference/index.md) | Vault languages. The entry with pwszLanguageCode="" is the default language. |
| `mds.named_references[].reference_type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The structure element type. |
| `mds.named_references[].name` | `string` | The name part of the named reference. |
| `mds.named_references[].element_id` | `int32` | The internal ID of the structure element. |
| `mds.named_references[].type_id` | `int32` | The internal ID of the structure element type. Relevant for MetadataStructureItem::valueListItem only, otherwise ignored. |
| `mds.languages[]` | repeated [`Language`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Language/index.md) | An array of the Language structures defining the vault languages. |
| `mds.languages[].id` | `int32` | Language ID. |
| `mds.languages[].name` | `string` | The name of the language. |
| `mds.languages[].language_code` | `string` | Language indentifier, e.g. the ISO 639-1 or ISO 639-2 language code such as "en" or "eng". |
| `mds.unknown_json` | `string` | Opaque JSON object of schema-recognized, converter-unmapped top-level properties, keyed by original property name. |
| `anomalies[]` | repeated [`MetadataStructureAnomaly`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureAnomaly/index.md) | Not read by the server. |
| `anomalies[].context` | [`MetadataStructureContext`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureContext/index.md) | The anomaly context. |
| `anomalies[].context.context_type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | The structure element type of the context. |
| `anomalies[].context.guid` | `string` | The GUID of the source. |
| `anomalies[].context.id` | `int32` | The internal ID of the source. |
| `anomalies[].context.type_id` | `int32` | The internal type ID of the source. Relevant for value list items only, otherwise ignored. |
| `anomalies[].context.name` | `string` | The name of the source. |
| `anomalies[].description` | `string` | The anomaly description. |
| `anomalies[].callstack` | `string` | The call stack of this anomaly occurrence. |

<a id="response"></a>

## Response: SetDeclarativeMetadataStructureAsProtobufResponse

No fields.

<a id="related"></a>

## Related methods

- [GetDeclarativeMetadataStructureAsProtobuf](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/GetDeclarativeMetadataStructureAsProtobuf/index.md): Gets the vault's current metadata structure as one typed message.

---

# IRPCDeclarativeMetadataStructureAsProtobuf.SetDeclarativeMetadataStructureBeginSessionAsProtobuf

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureBeginSessionAsProtobuf/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `returns metadata structure version`

Reserved for setting a structure in several parts. Not implemented.

- **Service:** [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md) `MFiles.IRPCDeclarativeMetadataStructureAsProtobuf`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureBeginSessionAsProtobuf`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-declarative-metadata-structure-begin-session-as-protobuf`
- **Request:** [`SetDeclarativeMetadataStructureBeginSessionAsProtobufRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureBeginSessionAsProtobuf/index.md#request)
- **Response:** [`SetDeclarativeMetadataStructureBeginSessionAsProtobufResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureBeginSessionAsProtobuf/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Always fails with "Not implemented.", whether or not the feature is enabled.

<a id="request"></a>

## Request: SetDeclarativeMetadataStructureBeginSessionAsProtobufRequest

No fields.

<a id="response"></a>

## Response: SetDeclarativeMetadataStructureBeginSessionAsProtobufResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `session` | `uint32` | Session identifier. |

---

# IRPCDeclarativeMetadataStructureAsProtobuf.SetDeclarativeMetadataStructureEndSessionAsProtobuf

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureEndSessionAsProtobuf/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session` `returns metadata structure version`

Reserved for setting a structure in several parts. Not implemented.

- **Service:** [Declarative metadata structure (protobuf)](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/index.md) `MFiles.IRPCDeclarativeMetadataStructureAsProtobuf`
- **gRPC method:** `/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureEndSessionAsProtobuf`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/set-declarative-metadata-structure-end-session-as-protobuf`
- **Request:** [`SetDeclarativeMetadataStructureEndSessionAsProtobufRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureEndSessionAsProtobuf/index.md#request)
- **Response:** [`SetDeclarativeMetadataStructureEndSessionAsProtobufResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCDeclarativeMetadataStructureAsProtobuf/SetDeclarativeMetadataStructureEndSessionAsProtobuf/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** yes (in the mfiles-metadata-version-bin trailer)
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

- Always fails with "Not implemented.", whether or not the feature is enabled.

<a id="request"></a>

## Request: SetDeclarativeMetadataStructureEndSessionAsProtobufRequest

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `session` | `uint32` | Session identifier. |
| `commit` | `bool` | True to commit the Set operation. |

<a id="response"></a>

## Response: SetDeclarativeMetadataStructureEndSessionAsProtobufResponse

No fields.

---

# Cloud management (IRPCCloudManagementApiOperations)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/

Gets the identity of the server in M-Files Manage, for client features that call M-Files cloud
services.

Provides methods for working with the Cloud Management API.

- **gRPC service:** `MFiles.IRPCCloudManagementApiOperations`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 1
- **Proto file:** [`mfiles/IRPCCloudManagementApiOperations.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCCloudManagementApiOperations.proto)

<a id="overview"></a>

## Overview

**For M-Files components only.** The M-Files desktop client reads the value when it sets up
document comparison. Applications should not call it.

The only method,
[GetCloudManagementApiConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/GetCloudManagementApiConfiguration/index.md),
needs a vault session and no special rights.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [GetCloudManagementApiConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/GetCloudManagementApiConfiguration/index.md) | Gets the server's ID in M-Files Manage. | `internal: not for applications` `admin` `session` |

---

# IRPCCloudManagementApiOperations.GetCloudManagementApiConfiguration

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Cloud management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/GetCloudManagementApiConfiguration/

Badges: `Administration API / specialized` `internal: not for applications` `admin` `session`

Gets the server's ID in M-Files Manage.

- **Service:** [Cloud management](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/index.md) `MFiles.IRPCCloudManagementApiOperations`
- **gRPC method:** `/MFiles.IRPCCloudManagementApiOperations/GetCloudManagementApiConfiguration`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/get-cloud-management-api-configuration`
- **Request:** [`GetCloudManagementApiConfigurationRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/GetCloudManagementApiConfiguration/index.md#request)
- **Response:** [`GetCloudManagementApiConfigurationResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCCloudManagementApiOperations/GetCloudManagementApiConfiguration/index.md#response)
- **Book and level:** Administration API, specialized
- **Kind:** admin
- **Session:** Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
- **Idempotent:** no
- **Returns metadata structure version:** no
- **Streaming:** none (unary)

<a id="remarks"></a>

## Remarks

**For M-Files components only.** The M-Files desktop client uses it for document comparison.
Applications should not call it.
- Requires a vault session; no special vault rights. A
  server-level session fails with "Login required.".
- `server_guid` is filled only on on-premises servers that are connected to M-Files Manage. It
  is empty on servers in M-Files Cloud containers (by design) and on servers without the
  connection.

<a id="request"></a>

## Request: GetCloudManagementApiConfigurationRequest

No fields.

<a id="response"></a>

## Response: GetCloudManagementApiConfigurationResponse

> Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

| Field | Type | Description |
|---|---|---|
| `configuration` | [`CloudManagementApiConfiguration`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CloudManagementApiConfiguration/index.md) | The server's M-Files Manage ID in `server_guid`, or empty. See [CloudManagementApiConfiguration](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.CloudManagementApiConfiguration/index.md). |
| `configuration.server_guid` | `string` | The server GUID. |